diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4e609ab..13e6943 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,7 +17,8 @@ jobs: with: node-version: "24" # The package has no dependencies and no lockfile, so there is nothing to install. - # The self-check needs no device and no socket: it reports both as absent and exits 0. + # The self-check and the regression suite need no device, no SidePulse and no + # OpenCode. compat.yml runs the tests that do. - run: npm test publish: diff --git a/.github/workflows/compat.yml b/.github/workflows/compat.yml new file mode 100644 index 0000000..db7f890 --- /dev/null +++ b/.github/workflows/compat.yml @@ -0,0 +1,96 @@ +name: compat + +# Runs the plugin against real releases of the two programs it sits between. The pinned +# entries are regression tests. The floating ones (SidePulse main, the latest OpenCode) +# also run every week, so a breaking change upstream shows up here first. +# +# None of these jobs gate the npm release. That is the `test` job in ci.yml. + +on: + pull_request: + push: + branches: [main] + schedule: + - cron: "17 5 * * 1" + workflow_dispatch: + +permissions: + contents: read + +jobs: + # OpenCode runs plugins under Bun. ci.yml runs the same suite under Node. + bun: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: oven-sh/setup-bun@v2 + - run: bun plugin.mjs + - run: bun test/run.mjs + + # Installs SidePulse at one commit, starts its real service, and drives the plugin + # against it. The first entry has no `sidepulse report`, so the plugin must fall back to + # the device. + sidepulse: + name: sidepulse ${{ matrix.name }} + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - name: 2026-10-13, before sidepulse report + ref: ffb1d3c2f3eed3b7e80e32d7876a7e1d67bd5dfb + args: --legacy + - name: 2026-11-10, first with sidepulse report + ref: ad4a5217fd3a833cfa2a12e1eaf055f22948cd53 + - name: 2026-11-12 + ref: 20ca7fdd6645ba070af607e24587084b6f809275 + - name: main + ref: main + steps: + - uses: actions/checkout@v6 + - uses: actions/checkout@v6 + with: + repository: inteliwear/sidepulse + ref: ${{ matrix.ref }} + path: upstream + persist-credentials: false + - uses: actions/setup-python@v6 + with: + python-version: "3.12" + - uses: actions/setup-node@v6 + with: + node-version: "24" + - run: python -m venv .venv && .venv/bin/pip install ./upstream + - run: .venv/bin/sidepulse --version + - run: node test/service.mjs ${{ matrix.args }} + env: + SIDEPULSE_BIN: ${{ github.workspace }}/.venv/bin/sidepulse + + # Installs one OpenCode release and runs real turns in it with the plugin loaded. + # OpenCode's free models need no account, so there are no secrets here. 1.18.0 is the + # oldest release the free models accept. + opencode: + name: opencode ${{ matrix.version }} + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - package: opencode-ai + version: 1.18.0 + - package: opencode-ai + version: 1.19.5 + - package: "@opencode/cli" + version: 2.1.2 + - package: "@opencode/cli" + version: 2.3.0 + - package: "@opencode/cli" + version: latest + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v6 + with: + node-version: "24" + - run: npm install --global "${{ matrix.package }}@${{ matrix.version }}" + - run: opencode --version + - run: node test/opencode.mjs diff --git a/.github/workflows/mutation.yml b/.github/workflows/mutation.yml new file mode 100644 index 0000000..f809bdf --- /dev/null +++ b/.github/workflows/mutation.yml @@ -0,0 +1,37 @@ +name: mutation + +# Mutation testing: Stryker changes the plugin one small piece at a time and reruns the +# tests. A change no test notices is a gap in the tests. The run fails when fewer than 85% +# of the changes are caught (see stryker.config.json). +# +# It takes about ten minutes, so it only runs when the plugin or its tests change. + +on: + pull_request: + paths: + - plugin.mjs + - test/** + - stryker.config.json + - .github/workflows/mutation.yml + workflow_dispatch: + +permissions: + contents: read + +jobs: + stryker: + runs-on: ubuntu-latest + timeout-minutes: 40 + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v6 + with: + node-version: "24" + # The package has no dependencies, so Stryker is fetched for this job only. + - run: npm run test:mutation + - if: always() + uses: actions/upload-artifact@v4 + with: + name: mutation-report + path: reports/mutation + if-no-files-found: ignore diff --git a/.gitignore b/.gitignore index 3c3629e..85e77fe 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ node_modules +.stryker-tmp/ +reports/ diff --git a/README.md b/README.md index 3cf58a3..4055010 100644 --- a/README.md +++ b/README.md @@ -77,37 +77,46 @@ tell you things you cannot see. You already know that you cancelled it. The green hold stays until the next turn starts. The device holds the last program, so the -plugin needs no timer to keep the color. +plugin needs no timer to keep the color. A failed turn stays red the same way. ## Two modes -The SidePulse menu-bar app also writes the LED control file. Two writers on one file +The SidePulse background service also writes the LED control file. Two writers on one file conflict, and the device restarts its animation on every write. This plugin avoids the -conflict. It picks a mode for each event: +conflict. It picks a mode for each status change: | Mode | Condition | Behavior | | --- | --- | --- | -| App | The app event socket answers. | Send a hook event. Never touch `LEDS.LED`. | -| Direct | No socket answers. | Write an LED program to `LEDS.LED`. | +| App | `sidepulse report` succeeds. | Report the session status. Never touch `LEDS.LED`. | +| Direct | The command is missing or fails. | Write an LED program to `LEDS.LED`. | Only one process ever writes the device. -In app mode the app owns the display. The app aggregates opencode together with Codex, +In app mode the service owns the display. It aggregates opencode together with Codex, Claude, and Grok, and it shows the most actionable state across all of them. The plugin -sends these upstream event names: +pipes one [program status](https://github.com/inteliwear/sidepulse/blob/main/docs/protocol/program-status.md) +report to `sidepulse report --json` whenever a session changes state: -| Plugin signal | `hook_event_name` | App mode | +| Plugin signal | Reported state | Shown as | | --- | --- | --- | -| Turn start | `UserPromptSubmit` | Working | -| Tool start | `PreToolUse` | Tool Running | -| Tool end | `PostToolUse` | Working | -| Permission prompt | `PermissionRequest` | Waiting For Input | -| Failure | `PostToolUseFailure` | Blocked / Error | -| Finished | `Stop` | Completed | -| Aborted | `SessionEnd` | Completed | +| Turn start, tool start, tool end | `working` | Working | +| Permission prompt | `blocked`, kind `permission` | Waiting for Input | +| Multiple-choice question | `blocked`, kind `question` | Waiting for Input | +| Prompt answered | `working` | Working | +| Failure, provider retry | `error` | Blocked / Error | +| Finished, cancelled | `done` | Completed | -The app needs no patch. Its ingest path accepts any provider name, so `opencode` appears -as a normal agent. `HOOK_PROVIDERS` in the upstream package only limits CLI arguments. +A report carries the session ID, the project directory and the state. It never carries +prompts, tool input or tool output. + +The plugin reports a session only when its state changes, so a run of tool calls costs +nothing. Reports go out one at a time, in order. Any report still queued when opencode +exits is sent before the process ends, so `opencode run` still finishes green. A session +that is still working or waiting when opencode exits is cleared, because the service never +expires those states by itself. + +The plugin looks for the command in `$SIDEPULSE_BIN`, then `~/.local/bin/sidepulse`, then +`PATH`. The service needs no patch: `opencode` appears as a normal agent. Direct mode needs no Python and no app. The device exposes its controller as a file, so a file write is the whole interface. @@ -118,22 +127,57 @@ file write is the whole interface. - OpenCode 2, or OpenCode 1.17.20 or newer. Older OpenCode 1 releases are not tested. If the plugin does not load on one of them, use `opencode-sidepulse@0.1.7`. - A SidePulse Pro or SidePulse Dot. +- For app mode, a SidePulse release that has the `sidepulse report` command. Upstream + added it on 10 November 2026. An older menu-bar app does not understand this plugin and + both would write the device, so update SidePulse or use `opencode-sidepulse@0.2.0`. The plugin needs no dependencies and no build step. It uses only Node standard library modules, so it runs the same under any opencode runtime. ## Test it -From a clone of this repository, under `node` or `bun`: +From a clone of this repository: ```sh -node plugin.mjs # program limits, state machine, device and socket discovery -node plugin.mjs --send # send one test event to a running app, and report delivery +npm test # the self-check, then the regression suite +node plugin.mjs --send # send one test report through the sidepulse CLI node plugin.mjs --demo # walk every LED state on the real device, four seconds each ``` -Use `--send` whenever you change the socket transport. App mode falls back to direct mode -on any failure, so a broken transport is otherwise invisible. +Use `--send` whenever you change the transport. App mode falls back to direct mode on any +failure, so a broken transport is otherwise invisible. The test report clears a session +that does not exist, so it leaves nothing in the menu. + +The tests come in four layers. None of them has a dependency to install. + +| Command | What it runs against | Needs | +| --- | --- | --- | +| `node test/run.mjs` | A fake `sidepulse` CLI and a folder standing in for the device. Covers both modes, the handover between them, ordering, exit, and event traces recorded from real OpenCode releases. | Nothing | +| `SIDEPULSE_BIN=… node test/service.mjs` | A real SidePulse install. Starts its service and reads back what it shows. Add `--legacy` for a SidePulse from before `sidepulse report`. | SidePulse | +| `OPENCODE_BIN=… node test/opencode.mjs` | A real OpenCode. Runs real turns on one of OpenCode's free models, which need no account. | OpenCode, network | +| `npm run test:mutation` | [Stryker](https://stryker-mutator.io) changes the plugin one piece at a time and reruns the first layer. It fails below 85% caught. | Network, about ten minutes | + +The first three also run under `bun`. `test/run.mjs` takes a word to run only the tests +whose name contains it, and `--keep` to keep the files of a failed test. + +CI runs all four. `compat.yml` pins the versions it checks: + +| Program | Versions | +| --- | --- | +| SidePulse | The commit before `sidepulse report`, the first commit with it, a later one, and `main` | +| OpenCode 1 | 1.18.0 and 1.19.5 | +| OpenCode 2 | 2.1.2, 2.3.0 and the latest release | + +The moving entries, SidePulse `main` and the latest OpenCode, also run every Monday. A +breaking change in either program then fails here first. OpenCode releases older than +1.18.0 cannot use the free models, so CI cannot run a turn in them. + +When a new OpenCode or SidePulse release changes behaviour, record what it sends, add it +to `test/run.mjs` as a trace, and add the version to `compat.yml`. + +Two environment variables exist for the tests. `SIDEPULSE_VOLUMES` replaces `/Volumes` as +the folder searched for the device. `SIDEPULSE_REPORT_TIMEOUT_MS` replaces the five +seconds the plugin waits for the CLI. Without a clone, check that the published package imports: @@ -143,25 +187,29 @@ bunx --package opencode-sidepulse bun -e \ # default opencode-sidepulse ``` -That confirms the package only. Use a clone for the self-check and the demo. +That confirms the package only. Use a clone for everything else. The LED language has no error channel. A program that fails to parse blinks all LEDs red six times. Watch the device during `--demo` to confirm each state. ## Known limits -- Direct mode tracks one state for all sessions. Run the menu-bar app if you need true - per-session aggregation. +- Direct mode tracks one state for all sessions. Run the SidePulse service if you need + true per-session aggregation. +- If opencode is killed mid-turn, the plugin cannot clear its sessions. They stay in the + SidePulse menu as Working until the service restarts. +- App mode does not name the running tool. The service draws a running tool the same way + as Working. - In direct mode the plugin touches `keepalive` once a minute. The MacBook SD card reader cuts power to the device after three minutes of inactivity. The device therefore goes - dark a few minutes after you quit opencode. In app mode the app owns the keepalive. + dark a few minutes after you quit opencode. In app mode the service owns the keepalive. - The device ignores LED indexes above its LED count. The programs target LEDs 0 to 3, so they work on the eight-LED Pro and degrade on the two-LED Dot. ## Credits SidePulse and its LED language come from [inteliwear/sidepulse](https://github.com/inteliwear/sidepulse) (MIT). -This plugin is an independent client of the documented file and socket interfaces. +This plugin is an independent client of the documented file and status report interfaces. ## License diff --git a/package.json b/package.json index fc59fe2..efcdc1e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "opencode-sidepulse", - "version": "0.2.0", + "version": "0.3.0", "description": "Show opencode agent status on a SidePulse Pro or SidePulse Dot LED device.", "keywords": [ "opencode", @@ -31,6 +31,7 @@ "LICENSE" ], "scripts": { - "test": "node plugin.mjs" + "test": "node plugin.mjs && node test/run.mjs", + "test:mutation": "npx --yes @stryker-mutator/core@10.1.1 run" } } diff --git a/plugin.mjs b/plugin.mjs index a102c1d..a795d5c 100644 --- a/plugin.mjs +++ b/plugin.mjs @@ -1,18 +1,20 @@ +import { spawn, spawnSync } from "node:child_process" +import { randomUUID } from "node:crypto" import { existsSync, readdirSync, utimesSync, writeFileSync } from "node:fs" -import { createConnection } from "node:net" import { homedir } from "node:os" import { join } from "node:path" // Two ways to drive a SidePulse device, picked per event: // -// App mode The SidePulse menu-bar app is running. Send hook events to its Unix -// socket and never touch LEDS.LED. The app aggregates opencode with -// Codex/Claude/Grok and owns the display, so there is no write conflict. -// Direct mode No app. Write an LED program straight to LEDS.LED. +// App mode The SidePulse background service is running. Report each session's status +// with `sidepulse report --json` and never touch LEDS.LED. The service +// aggregates opencode with Codex/Claude/Grok and owns the display, so there +// is no write conflict. +// Direct mode No service. Write an LED program straight to LEDS.LED. // // Both paths are documented by the upstream project: -// socket protocol https://github.com/inteliwear/sidepulse/blob/main/src/sidepulse/ipc.py -// LED DSL https://github.com/inteliwear/sidepulse/blob/main/LEDS_FORMAT.md +// status reports https://github.com/inteliwear/sidepulse/blob/main/docs/protocol/program-status.md +// LED DSL https://github.com/inteliwear/sidepulse/blob/main/LEDS_FORMAT.md // ---------------------------------------------------------------- direct mode @@ -38,10 +40,13 @@ const PROGRAMS = { // rules out "SidePulseDot". const VOLUME = /^(sidepulse|pulsedot)/i +// macOS mounts the device under /Volumes. The override lets the tests use a plain folder. +const VOLUMES = process.env.SIDEPULSE_VOLUMES || "/Volumes" + function mount() { try { - for (const name of readdirSync("/Volumes")) { - const dir = join("/Volumes", name) + for (const name of readdirSync(VOLUMES)) { + const dir = join(VOLUMES, name) if (VOLUME.test(name) && existsSync(join(dir, "LEDS.LED"))) return dir } } catch {} @@ -69,64 +74,139 @@ function write(state) { // ------------------------------------------------------------------- app mode -// Upstream default_state_dir() honors XDG_STATE_HOME from its OWN environment. The app is -// launched by launchd and usually has none, while opencode may well have one set (the -// opencode desktop app sets it per-app). The two processes therefore disagree on the path, -// so probe every candidate instead of computing one. -const CANDIDATES = [ - ...new Set([ - ...(process.env.XDG_STATE_HOME ? [process.env.XDG_STATE_HOME] : []), - join(homedir(), ".local", "state"), - ]), -].map((base) => join(base, "sidepulse", "agent-monitor", "events.sock")) - -function socket() { - return CANDIDATES.find((path) => existsSync(path)) +// The service keeps one status per session and renders the LEDs itself. Its documented +// input is the `sidepulse report` command, so nothing here depends on socket paths or the +// wire format. The command exits non-zero when no service answers, and that exit code is +// what selects direct mode. +// +// This replaces the app's events.sock. That socket still accepts a connection, but since +// upstream moved session state into the service it ignores everything except "open +// settings". The old transport therefore reported success while the device showed nothing. + +// The upstream installer puts the CLI in ~/.local/bin. The opencode desktop app is started +// by launchd and often has no such entry on PATH, so look there before trusting PATH. +function command() { + if (process.env.SIDEPULSE_BIN) return process.env.SIDEPULSE_BIN + const installed = join(homedir(), ".local", "bin", "sidepulse") + return existsSync(installed) ? installed : "sidepulse" } -// The app reads one JSON object per connection and stops at EOF, so the client must -// half-close after writing. end(payload) writes and then sends FIN, which is that EOF. -// Upstream caps a message at 1 MiB; ours are tiny. -// -// Use node:net, not Bun.connect. Bun globals are not reachable from an npm-installed -// plugin, so Bun.connect threw ReferenceError, the catch below swallowed it, and app mode -// silently degraded to direct mode. node:net is stdlib and works under any runtime. -// -// Any failure resolves false so the caller falls back to direct mode instead of throwing -// into a hook. -function send(path, event, sessionID, cwd, tool) { - const payload = JSON.stringify({ - provider: "opencode", - line: { - hook_event_name: event, - session_id: sessionID, - cwd, - // Upstream origin_label_from_payload() reads this key, so the app labels the agent - // instead of leaving origin empty. Providers it does not know get no origin at all. - agent_origin: "opencode", - ...(tool ? { tool_name: tool } : {}), - }, - }) +const ARGS = ["report", "--json"] +const STDIO = ["pipe", "ignore", "ignore"] +// The CLI gives the service half a second. The rest is Python startup. +const REPORT_TIMEOUT_MS = Number(process.env.SIDEPULSE_REPORT_TIMEOUT_MS) || 5000 + +// Resolves true only when the service accepted the report. A missing CLI, a stopped +// service and a hung process all resolve false, so the caller falls back to direct mode +// instead of throwing into a hook. +function run(body) { return new Promise((resolve) => { - let socket - // Never let a hung socket stall a turn. Upstream uses a 200 ms timeout; match it. - const timer = setTimeout(() => { - socket?.destroy() - resolve(false) - }, 200) + let child + const timer = setTimeout(() => child?.kill(), REPORT_TIMEOUT_MS) + timer.unref?.() const finish = (ok) => { clearTimeout(timer) resolve(ok) } try { - socket = createConnection({ path }, () => socket.end(payload, () => finish(true))) - socket.on("error", () => finish(false)) + // Detached and unref'd, so a report never holds the process open and is not taken + // down with opencode's process group. + child = spawn(command(), ARGS, { detached: true, stdio: STDIO, windowsHide: true }) + child.once("error", () => finish(false)) + child.once("exit", (code) => finish(code === 0)) + child.stdin.on("error", () => {}) + child.stdin.end(body) + child.unref() } catch { finish(false) } }) } +// One report for the service. Only identity and state: no prompt, tool input or output. +function reportBody(sessionID, status, cwd) { + return JSON.stringify({ + v: 1, + type: "program_status", + scope: `opencode-${sessionID}`, + request_id: randomUUID(), + status: { ...status, app: "opencode" }, + context: { provider: "opencode", session_id: sessionID, ...(cwd ? { cwd } : {}) }, + }) +} + +// True while the service accepts reports. It owns the LEDs and the keepalive then. +let appAlive = false + +// The LED state the service last declined. Direct mode owns that state until it changes. +let declined + +// Reports go out one at a time and in order. Each one is a separate process, so two in +// flight could land swapped, and the service never expires a Working status on its own: +// a "working" that overtakes its "done" would spin until the service restarts. +const pending = [] +let inflight + +async function pump() { + if (inflight) return + while ((inflight = pending.shift())) { + try { + const ok = await run(inflight.body) + // The exit flush below may have taken this report over while it was in flight. + if (inflight) settle(inflight, ok) + } catch {} + inflight = undefined + } +} + +function settle(job, ok) { + appAlive = ok + if (ok) { + declined = undefined + shown = undefined // the service owns the LEDs now; repaint if we take over later + return + } + // Not delivered, so the next event for this session must be reported again. + if (reported.get(job.sessionID) === job.key) reported.delete(job.sessionID) + // A clear has no LED state. It only tidies the service. + if (!job.state) return + declined = job.state + write(job.state) +} + +// `opencode run` exits as soon as the turn ends, with the final report still queued or in +// flight. Send what is left synchronously. The report in flight goes first so the queue +// cannot overtake it. It is sent again even when nothing is queued behind it: its process +// is detached, but its body may not have left this process yet, and Bun drops a body that +// was written in the same tick as the exit. It keeps its request_id, and the service +// applies a repeated request_id only once, so a second copy changes nothing. +// +// A session still working or waiting at exit can never finish, and the service never +// expires those states on its own: the device would stay lit for a prompt nobody can +// answer. Clear those sessions. Done and error stay, because they are still news. +process.once("exit", () => { + for (const [sessionID, key] of reported) + if (key.startsWith("working") || key.startsWith("blocked")) + pending.push({ sessionID, body: reportBody(sessionID, { state: "clear" }) }) + const jobs = [...(inflight ? [inflight] : []), ...pending.splice(0)] + inflight = undefined + for (const job of jobs) { + // No service, so nothing to clear. Do not start a process per session to find out. + if (!job.state && !appAlive) continue + let ok = false + try { + const result = spawnSync(command(), ARGS, { + input: job.body, + stdio: STDIO, + timeout: REPORT_TIMEOUT_MS, + windowsHide: true, + }) + ok = result.status === 0 + } catch {} + settle(job, ok) + } +}) + // ------------------------------------------------------------------- dispatch // Tools that block on you instead of doing work. `question` is opencode's multiple-choice @@ -172,8 +252,8 @@ function signalForEvent(type, props) { // A permission prompt outranks a tool finishing, so a tool cannot stomp the amber // prompt back to cyan. -// ponytail: one global flag, not per-session aggregation. In app mode the app does real -// per-session aggregation, so this only shapes direct mode. +// ponytail: one global flag, not per-session aggregation. In app mode the service does +// real per-session aggregation, so this only shapes direct mode. let waiting = false // True between a user message and the end of that turn. A cancelled turn can still settle @@ -187,21 +267,24 @@ let turnActive = false let retrying = false -// Each signal carries the LED state for direct mode and the upstream event name for app -// mode. Both mappings are verified against the upstream collector. +// Each signal carries the LED state for direct mode and the program-status state for app +// mode. The service renders working, blocked, error and done as Working, Waiting for +// Input, Blocked / Error and Completed. const SIGNALS = { - start: { state: "busy", event: "UserPromptSubmit" }, - "tool-start": { state: "busy", event: "PreToolUse" }, - "tool-end": { state: "hold", event: "PostToolUse" }, - ask: { state: "waiting", event: "PermissionRequest" }, - reply: { state: "busy", event: "UserPromptSubmit" }, - idle: { state: "done", event: "Stop" }, - error: { state: "error", event: "PostToolUseFailure" }, + start: { state: "busy", status: "working" }, + // Tool churn stays "working" in app mode. The service draws Tool Running exactly like + // Working, and an unchanged status is not reported, so tools cost no process spawn. + "tool-start": { state: "busy", status: "working" }, + "tool-end": { state: "hold", status: "working" }, + ask: { state: "waiting", status: "blocked" }, + reply: { state: "busy", status: "working" }, + idle: { state: "done", status: "done" }, + error: { state: "error", status: "error" }, // A retry is a recoverable failure, which is upstream's own definition of // Blocked / Error. Reuse the error colour rather than add a sixth program: the point is // that the turn has stalled, and a stall that looks like work is the whole problem. - retry: { state: "error", event: "PostToolUseFailure" }, - resume: { state: "busy", event: "PostToolUse" }, + retry: { state: "error", status: "error", msg: "Retrying a failed provider call" }, + resume: { state: "busy", status: "working" }, } const TERMINAL = new Set(["idle", "error"]) @@ -220,33 +303,65 @@ function stateFor(signal) { return wanted } -// Never throw into a hook. A status light must not be able to break a turn. -async function report(signal, sessionID, cwd, tool) { +// App mode status. The service keeps one status per session, so the open prompt is tracked +// per session here: the global flag above would let a prompt in one session mark another +// session as blocked. A prompt outranks tool churn in its own session and nothing else. +const prompts = new Map() // sessionID -> kind of the open prompt + +function statusFor(signal, sessionID, tool) { + if (signal === "ask") prompts.set(sessionID, BLOCKING_TOOLS.has(tool) ? "question" : "permission") + else if (signal !== "tool-start" && signal !== "tool-end") prompts.delete(sessionID) + const kind = prompts.get(sessionID) + if (kind) return { state: "blocked", kind } + const { status, msg } = SIGNALS[signal] + return { state: status, ...(msg ? { msg } : {}) } +} + +// Sessions whose turn ended in an error. OpenCode 1 follows session.error with +// session.idle, and that idle would paint a failed turn green. Measured on 1.19.5. +const failed = new Set() + +// The last status handed to the queue for each session. An unchanged status is skipped. +// ponytail: never pruned. It holds one short string per session for the process lifetime. +const reported = new Map() + +// Never throw into a hook, and never make one wait: the report is queued and the hook +// returns. A status light must not be able to break a turn or slow it down. +function report(signal, sessionID, cwd, tool) { try { + if (signal === "error") failed.add(sessionID) + else if (signal !== "idle") failed.delete(sessionID) + else if (failed.has(sessionID)) return const state = stateFor(signal) - // Prefer the app. Only fall through when no socket answers, which also covers a - // stale socket file left behind by a crash. - const path = socket() - if (path && (await send(path, SIGNALS[signal].event, sessionID, cwd, tool))) { - shown = undefined // the app owns the LEDs now; repaint if we take over later - return - } - write(state) + const status = statusFor(signal, sessionID, tool) + const key = `${status.state}:${status.kind ?? ""}` + // The service has this status, or is about to. + if (reported.get(sessionID) === key) return + // Direct mode, and the service already declined this state. Paint, which is free when + // nothing changed, and ask the service again on the next change instead of starting a + // process for every tool call. + if (!appAlive && state === declined) return void write(state) + reported.set(sessionID, key) + pending.push({ state, sessionID, key, body: reportBody(sessionID, status, cwd) }) + // Prefer the service. A report it does not accept falls back to direct mode in settle(). + pump() } catch {} } // The MacBook SD reader cuts power to the device after three minutes of inactivity. -// The app does its own keepalive, so only do it when the app is absent. +// The service does its own keepalive, so only do it when the service is absent. +function beat() { + if (appAlive) return + const dir = mount() + if (!dir) return + try { + const now = new Date() + utimesSync(join(dir, "keepalive"), now, now) + } catch {} +} + function keepalive() { - const alive = setInterval(() => { - if (socket()) return - const dir = mount() - if (!dir) return - try { - const now = new Date() - utimesSync(join(dir, "keepalive"), now, now) - } catch {} - }, 60_000) + const alive = setInterval(beat, 60_000) // Do not hold the process open on exit. alive.unref?.() return () => clearInterval(alive) @@ -308,9 +423,10 @@ const plugin = { export default plugin +// Stryker disable all: everything below is test code, not plugin code. // Self-check. Run it with: node plugin.mjs (also works under bun) // --demo walk every LED state on the device, four seconds each -// --send send one test event to a live app socket and report the result +// --send send one test report through the sidepulse CLI and print the result // opencode imports this file, so this block stays out of the plugin path. import.meta.main // is a bun-ism, so check argv too, which keeps the check runnable under plain node. const selfCheck = @@ -359,35 +475,40 @@ if (selfCheck) { if (turnActive) throw new Error(`${terminal} left the turn armed`) } - // In app mode the app owns the display, so the event we send matters more than the - // local state. These mode mappings were measured against a live menu-bar app by - // sending each event and reading back latest.json. Checking the local state alone - // missed a cancel finishing green, because SessionEnd renders as Completed. - const APP_MODES = { - SessionStart: "idle_ready", - UserPromptSubmit: "working", - PreToolUse: "tool_running", - PostToolUse: "working", - PermissionRequest: "waiting_for_input", - PostToolUseFailure: "blocked_error", - Stop: "completed", - SessionEnd: "completed", - } - const WANT_APP_MODE = { + // In app mode the service owns the display, so the status we report matters more than + // the local state. Checking the local state alone once missed a cancel finishing green. + const WANT_STATUS = { start: "working", - "tool-start": "tool_running", + "tool-start": "working", "tool-end": "working", - ask: "waiting_for_input", + ask: "blocked", reply: "working", - idle: "completed", - error: "blocked_error", - retry: "blocked_error", + idle: "done", + error: "error", + retry: "error", resume: "working", } - for (const [signal, wantMode] of Object.entries(WANT_APP_MODE)) { - const event = SIGNALS[signal].event - if (APP_MODES[event] !== wantMode) - throw new Error(`${signal} sends ${event}, which the app renders as ${APP_MODES[event]}, want ${wantMode}`) + for (const [signal, wantStatus] of Object.entries(WANT_STATUS)) { + const actual = statusFor(signal, "check-status").state + if (actual !== wantStatus) throw new Error(`${signal} reports ${actual}, want ${wantStatus}`) + } + + // A prompt holds its own session at blocked through tool churn, names its kind, and + // leaves every other session alone. + const sessions = [ + ["ask", "a", undefined, "blocked:permission"], + ["tool-end", "a", "bash", "blocked:permission"], + ["tool-start", "a", "bash", "blocked:permission"], + ["tool-end", "b", "bash", "working:"], + ["reply", "a", undefined, "working:"], + ["ask", "a", "question", "blocked:question"], + ["idle", "a", undefined, "done:"], + ["tool-end", "a", "bash", "working:"], + ] + for (const [signal, id, tool, wantKey] of sessions) { + const status = statusFor(signal, `check-${id}`, tool) + const actual = `${status.state}:${status.kind ?? ""}` + if (actual !== wantKey) throw new Error(`session ${id} ${signal}: reports ${actual}, want ${wantKey}`) } // Real traces, captured from the desktop app with a logging probe. Replaying them is @@ -448,24 +569,25 @@ if (selfCheck) { console.log(`ok: ${Object.keys(PROGRAMS).length} programs, ${want.length} transitions`) console.log(` device ${mount() ?? "not mounted"}`) - console.log(` app socket ${socket() ?? "absent, using direct mode"}`) - for (const path of CANDIDATES) console.log(` probed ${path}`) + console.log(` app CLI ${command()}`) const sleep = (ms) => new Promise((r) => setTimeout(r, ms)) - // Exercise the real send(), so a broken transport cannot hide behind the direct-mode + // Exercise the real run(), so a broken transport cannot hide behind the direct-mode // fallback. This is the check that would have caught the Bun.connect regression. if (process.argv.includes("--send")) { - const path = socket() - if (!path) { - console.log(" --send: no app socket, nothing to test") - } else { - // SessionStart renders Idle / Ready, which upstream marks stale immediately, so - // this proves delivery without leaving a visible agent behind for 20 minutes. - const ok = await send(path, "SessionStart", "selfcheck-session", process.cwd()) - console.log(` --send: ${ok ? "delivered to" : "FAILED against"} ${path}`) - if (!ok) process.exitCode = 1 - } + // run() unrefs its child so it can never hold opencode open. Nothing else is running + // here, so hold the process open until the CLI answers. + const hold = setInterval(() => {}, 1000) + // "clear" removes a session, so this proves delivery and leaves nothing in the menu. + const ok = await run(reportBody("selfcheck", { state: "clear" })) + clearInterval(hold) + console.log( + ok + ? " --send: accepted by the SidePulse service" + : " --send: NOT accepted. Check `sidepulse service status`. Direct mode would be used.", + ) + if (!ok) process.exitCode = 1 } if (process.argv.includes("--demo")) { diff --git a/stryker.config.json b/stryker.config.json new file mode 100644 index 0000000..dc7f86d --- /dev/null +++ b/stryker.config.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://raw.githubusercontent.com/stryker-mutator/stryker-js/master/packages/core/schema/stryker-schema.json", + "testRunner": "command", + "commandRunner": { + "command": "node plugin.mjs && node test/run.mjs" + }, + "mutate": [ + "plugin.mjs" + ], + "coverageAnalysis": "off", + "reporters": [ + "clear-text", + "progress", + "html", + "json" + ], + "htmlReporter": { + "fileName": "reports/mutation/mutation.html" + }, + "jsonReporter": { + "fileName": "reports/mutation/mutation.json" + }, + "thresholds": { + "high": 95, + "low": 90, + "break": 85 + }, + "timeoutMS": 60000, + "tempDirName": ".stryker-tmp" +} diff --git a/test/driver.mjs b/test/driver.mjs new file mode 100644 index 0000000..83edac6 --- /dev/null +++ b/test/driver.mjs @@ -0,0 +1,179 @@ +// Runs one scenario against the plugin in a fresh process, so module state starts clean and +// the exit hook really runs. run.mjs starts one of these per test. +// +// Steps are JSON arrays: +// ["prompt", session] the user sent a message +// ["before", session, tool] tool.execute.before +// ["after", session, tool] tool.execute.after +// ["event", type, payload] a bus event +// ["service", "up" | "down"] start or stop the fake service +// ["delay", seconds] make the next CLI call slow +// ["led"] record what LEDS.LED holds now +// ["write-led", text] overwrite LEDS.LED, as the service would +// ["beat"] run one keepalive tick +// ["status"] record what the real service shows (service.mjs only) +// ["dispose"] unload the plugin +// ["exit"] leave at once, like `opencode run` +// ["fast", [steps]] run steps without waiting for reports, during or after +// ["drain"] wait for the report queue to empty +// Every step except "fast" waits until the report queue is empty before the next one starts. + +import { spawnSync } from "node:child_process" +import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs" +import { join } from "node:path" +import { pathToFileURL } from "node:url" + +const scenario = JSON.parse(process.env.SCENARIO) +const dir = process.env.SCENARIO_DIR +const fake = process.env.FAKE_SIDEPULSE_DIR +const led = process.env.SCENARIO_LED + +// The plugin exports only its default object, on purpose. To see inside, load a copy with +// one extra export. Nothing in the published file changes for the tests. +const source = readFileSync(new URL("../plugin.mjs", import.meta.url), "utf8") +const copy = join(dir, "plugin.under-test.mjs") +writeFileSync( + copy, + `${source}\nexport const internals = { drained: () => !inflight && !pending.length, beat }\n`, +) +const { default: plugin, internals } = await import(pathToFileURL(copy).href) + +const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) + +async function drain() { + const deadline = Date.now() + 10_000 + while (!internals.drained()) { + if (Date.now() > deadline) throw new Error("the report queue never emptied") + await sleep(1) + } +} + +const results = { id: plugin.id, leds: [], keepalive: [], status: [] } +const save = () => writeFileSync(join(dir, "result.json"), JSON.stringify(results)) + +// ------------------------------------------------------------- fake OpenCode + +const directory = "/projects/demo" +let hooks +let unload + +// OpenCode 1 hands hooks back from server() and carries event payloads in `properties`. +async function v1() { + const h = await plugin.server({ directory }) + hooks = { + prompt: (sessionID) => h["chat.message"]({ sessionID }), + before: (sessionID, tool) => h["tool.execute.before"]({ tool, sessionID }), + after: (sessionID, tool) => h["tool.execute.after"]({ tool, sessionID }), + event: (type, properties) => h.event({ event: { type, properties } }), + } + unload = () => h.dispose() +} + +// OpenCode 2 registers hooks on a context, streams events, and carries payloads in `data`. +async function v2() { + const registered = {} + const queue = [] + let wake + let ended = false + const ctx = { + location: { directory }, + session: { hook: async (name, fn) => void (registered[`session.${name}`] = fn) }, + tool: { hook: async (name, fn) => void (registered[`tool.${name}`] = fn) }, + event: { + subscribe: ({ signal }) => + (async function* () { + signal.addEventListener("abort", () => wake?.()) + while (!signal.aborted) { + const next = queue.shift() + if (!next) { + await new Promise((resolve) => (wake = resolve)) + continue + } + yield next.event + // The consumer asked for the next event, so it has finished with this one. + next.handled() + } + // Unsubscribed. Later events reach nobody. + ended = true + for (const left of queue.splice(0)) left.handled() + })(), + }, + } + const stop = await plugin.setup(ctx) + hooks = { + prompt: (sessionID) => registered["session.prompt"]({ sessionID }), + before: (sessionID, tool) => registered["tool.execute.before"]({ tool, sessionID }), + after: (sessionID, tool) => registered["tool.execute.after"]({ tool, sessionID }), + event: (type, data) => + new Promise((handled) => { + if (ended) return handled() + queue.push({ event: { type, data }, handled }) + wake?.() + }), + } + unload = () => stop() +} + +// ------------------------------------------------------------------- steps + +async function step([name, ...args], wait = true) { + switch (name) { + case "prompt": + case "before": + case "after": + case "event": + await hooks[name](...args) + break + case "service": + if (args[0] === "up") writeFileSync(join(fake, "up"), "") + else rmSync(join(fake, "up"), { force: true }) + break + case "delay": + writeFileSync(join(fake, "delay-once"), String(args[0])) + break + case "led": + results.elapsedToFirstLed ??= Date.now() - started + results.leds.push(existsSync(led) ? readFileSync(led, "utf8") : null) + save() + break + case "write-led": + writeFileSync(led, args[0]) + break + case "beat": { + internals.beat() + const file = join(led, "..", "keepalive") + results.keepalive.push(existsSync(file) ? Date.now() - statSync(file).mtimeMs < 60_000 : null) + save() + break + } + case "status": { + const { stdout } = spawnSync(process.env.SIDEPULSE_BIN, ["status", "--json", "--all"], { encoding: "utf8" }) + const snapshot = JSON.parse(stdout.split("\n")[0]) + const rows = [...snapshot.statuses, ...snapshot.stale_statuses] + results.status.push( + Object.fromEntries(rows.map((row) => [row.session_id, row.message ? `${row.mode} (${row.message})` : row.mode])), + ) + save() + break + } + case "dispose": + await unload() + break + case "exit": + process.exit(0) + case "fast": + for (const inner of args[0]) await step(inner, false) + return + case "drain": + break + default: + throw new Error(`unknown step ${name}`) + } + if (wait) await drain() +} + +await (scenario.opencode === 2 ? v2() : v1()) +const started = Date.now() +for (const next of scenario.steps) await step(next) +save() +await unload() diff --git a/test/fake-sidepulse b/test/fake-sidepulse new file mode 100755 index 0000000..35b0220 --- /dev/null +++ b/test/fake-sidepulse @@ -0,0 +1,26 @@ +#!/bin/sh +# A stand-in for the `sidepulse` CLI. It records every report it is given and answers the +# way the real command does: exit 0 when the service accepted the report, 1 when no +# service answers, 2 for a command it does not know. +# +# The test controls it through files in $FAKE_SIDEPULSE_DIR: +# up present: the service is running +# delay-once seconds to wait before answering, used up by the first call that sees it +# hang present: never answer +# It writes: +# reports.jsonl one accepted report per line +# declined.jsonl one report per line that arrived while the service was down +dir=${FAKE_SIDEPULSE_DIR:?} +[ "$1" = report ] && [ "$2" = --json ] || exit 2 +body=$(cat) +[ -e "$dir/hang" ] && exec sleep 30 +if [ -e "$dir/delay-once" ]; then + delay=$(cat "$dir/delay-once") + rm -f "$dir/delay-once" + sleep "$delay" +fi +if [ ! -e "$dir/up" ]; then + printf '%s\n' "$body" >> "$dir/declined.jsonl" + exit 1 +fi +printf '%s\n' "$body" >> "$dir/reports.jsonl" diff --git a/test/opencode.mjs b/test/opencode.mjs new file mode 100644 index 0000000..c8c7cb9 --- /dev/null +++ b/test/opencode.mjs @@ -0,0 +1,154 @@ +// Runs real turns in a real OpenCode with the plugin loaded. Use it to check an OpenCode +// version: +// +// OPENCODE_BIN=/path/to/opencode node test/opencode.mjs +// +// OpenCode offers free models that need no account, so this needs no credentials. It does +// need the network. Each run sends two short prompts to a free model. Set OPENCODE_MODEL +// to choose the model, for example opencode/big-pickle. +// +// Everything OpenCode writes goes to a throwaway home folder. The plugin is loaded from +// the global plugins folder, the fake `sidepulse` CLI stands in for the service, and a +// folder stands in for the device. CI runs this against pinned OpenCode releases and +// against the latest one. + +import { spawnSync } from "node:child_process" +import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { fileURLToPath } from "node:url" +import { isDeepStrictEqual } from "node:util" + +const bin = process.env.OPENCODE_BIN ?? "opencode" +const here = fileURLToPath(new URL(".", import.meta.url)) +const LED = { + untouched: "untouched\n", + error: "off\n#ff2000 0.9s pulse\nrepeat\n", + done: "#00ff22 0.6s cosine\n", +} + +const dir = realpathSync(mkdtempSync(join(tmpdir(), "opencode-sidepulse-live-"))) +const home = join(dir, "home") +const project = join(dir, "project") +const fake = join(dir, "fake") +const led = join(dir, "volumes", "SidePulse", "LEDS.LED") +for (const made of [project, fake, join(dir, "volumes", "SidePulse"), join(home, ".config", "opencode", "plugins")]) + mkdirSync(made, { recursive: true }) +copyFileSync(join(here, "..", "plugin.mjs"), join(home, ".config", "opencode", "plugins", "sidepulse.js")) + +const env = { + ...process.env, + HOME: home, + XDG_CONFIG_HOME: join(home, ".config"), + XDG_DATA_HOME: join(home, ".local", "share"), + XDG_STATE_HOME: join(home, ".local", "state"), + XDG_CACHE_HOME: join(home, ".cache"), + // OpenCode 1 takes the project directory from PWD, not from the working directory. + PWD: project, + SIDEPULSE_BIN: join(here, "fake-sidepulse"), + SIDEPULSE_VOLUMES: join(dir, "volumes"), + FAKE_SIDEPULSE_DIR: fake, +} + +// stdin is closed on purpose. OpenCode 1 reads a piped stdin as part of the prompt and +// waits on an open one for ever. +const opencode = (args, timeout = 60_000) => + spawnSync(bin, args, { env, cwd: project, encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] }) + +const version = opencode(["--version"]).stdout?.match(/\d+\.\d+\.\d+/)?.[0] +if (!version) { + console.error(`Could not run ${bin}. Set OPENCODE_BIN to a real opencode.`) + process.exit(2) +} +// The flags differ between releases, so ask this one what it has. OpenCode 1 prints help +// to stderr. +const helpRun = opencode(["run", "--help"]) +const help = `${helpRun.stdout ?? ""}${helpRun.stderr ?? ""}` +const flags = ["--standalone", "--auto"].filter((flag) => help.includes(flag)) +// OpenCode 2 starts a shared background service unless told to keep its server private. +// A service left behind would outlive this test, so every call here stays private. +const standalone = flags.filter((flag) => flag === "--standalone") + +const free = (opencode(["models", ...standalone]).stdout ?? "") + .split("\n") + .map((line) => line.trim()) + .filter((line) => line.startsWith("opencode/")) + .sort((a, b) => b.includes("big-pickle") - a.includes("big-pickle")) +const models = process.env.OPENCODE_MODEL ? [process.env.OPENCODE_MODEL] : free.slice(0, 4) +console.log(`OpenCode ${version}, flags ${flags.join(" ") || "none"}, models ${models.join(", ") || "none"}`) + +let failures = 0 +function check(name, got, want) { + if (isDeepStrictEqual(got, want)) return console.log(`ok ${name}`) + failures++ + console.log(`FAILED ${name}\n want ${JSON.stringify(want)}\n got ${JSON.stringify(got)}`) +} + +// One real turn. Returns what the plugin told the service and what the device shows. +function turn(model, prompt, { service }) { + if (service) writeFileSync(join(fake, "up"), "") + else rmSync(join(fake, "up"), { force: true }) + for (const log of ["reports.jsonl", "declined.jsonl"]) rmSync(join(fake, log), { force: true }) + writeFileSync(led, LED.untouched) + const run = opencode(["run", ...flags, "-m", model, prompt], 180_000) + const read = (log) => { + const file = join(fake, log) + const seen = new Set() + return (existsSync(file) ? readFileSync(file, "utf8") : "") + .split("\n") + .filter(Boolean) + .map((line) => JSON.parse(line)) + .filter((body) => !seen.has(body.request_id) && seen.add(body.request_id)) + } + const reports = read("reports.jsonl") + return { + code: run.status, + output: `${run.stdout ?? ""}${run.stderr ?? ""}`.trim().split("\n").slice(-12).join("\n"), + states: reports.map((body) => body.status.state), + sessions: [...new Set(reports.map((body) => body.scope))], + cwds: [...new Set(reports.map((body) => body.context?.cwd))], + declined: read("declined.jsonl").length, + led: readFileSync(led, "utf8"), + } +} + +const TASK = "Use your shell tool to run this exact command: echo sidepulse-test. Then reply with the single word ok." + +// A free model can be retired or busy, so try a few before calling it a failure. +let model +let finished +for (const candidate of models) { + finished = turn(candidate, TASK, { service: true }) + if (finished.code === 0) { + model = candidate + break + } + console.log(` ${candidate} did not finish a turn (exit ${finished.code}), trying the next model`) +} + +if (!model) { + failures++ + console.log(`FAILED no free model finished a turn\n${finished?.output ?? "opencode models listed no free model"}`) +} else { + check(`a real turn on ${model} reports working, then done`, finished.states, ["working", "done"]) + check("the turn is one session", finished.sessions.length, 1) + check("the session is OpenCode's own", /^opencode-ses_/.test(finished.sessions[0] ?? ""), true) + check("reports carry the project directory", finished.cwds, [project]) + check("the device is left alone while the service runs", finished.led, LED.untouched) + + const direct = turn(model, TASK, { service: false }) + check("service down: the turn ends green on the device", direct.led, LED.done) + check("service down: the service was asked, and applied nothing", [direct.declined > 0, direct.states], [true, []]) +} + +// A model that does not exist fails the turn without any model at all. +const broken = turn("opencode/no-such-model", "Reply ok.", { service: true }) +check("a failed turn exits non-zero", broken.code !== 0, true) +check("a failed turn reports working, then error, and stays there", broken.states, ["working", "error"]) + +const brokenDirect = turn("opencode/no-such-model", "Reply ok.", { service: false }) +check("service down: a failed turn ends red on the device", brokenDirect.led, LED.error) + +if (failures) console.log(`\n${failures} failed. Last output:\n${broken.output}\nFiles kept in ${dir}`) +else rmSync(dir, { recursive: true, force: true }) +process.exitCode = failures ? 1 : 0 diff --git a/test/run.mjs b/test/run.mjs new file mode 100644 index 0000000..f031aaa --- /dev/null +++ b/test/run.mjs @@ -0,0 +1,801 @@ +// Regression tests for the plugin. Run with: node test/run.mjs (or bun test/run.mjs) +// Pass a word to run only the tests whose name contains it. Add --keep to keep the folders +// of failed tests for a look. +// +// Each test drives the real plugin through fake OpenCode hooks in its own process (see +// driver.mjs), with a fake `sidepulse` CLI and a folder standing in for the device. It then +// compares what the service was told and what was written to LEDS.LED. +// +// No dependencies, like the plugin. It needs a POSIX shell for the fake CLI. + +import { spawn } from "node:child_process" +import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs" +import { availableParallelism, tmpdir } from "node:os" +import { delimiter, join } from "node:path" +import { fileURLToPath } from "node:url" +import { isDeepStrictEqual } from "node:util" + +const here = fileURLToPath(new URL(".", import.meta.url)) +const FAKE_CLI = join(here, "fake-sidepulse") +const DRIVER = join(here, "driver.mjs") + +// The LED programs, copied here on purpose. A change to what the device shows must be made +// twice, once in the plugin and once here. +const LED = { + busy: "off\n0:#00ccff 1:#0088cc 2:#004466 3:#001a26\nroll 1.2s linear\nrepeat\n", + waiting: "off\n#ffb000 1.4s pulse\nrepeat\n", + error: "off\n#ff2000 0.9s pulse\nrepeat\n", + done: "#00ff22 0.6s cosine\n", + untouched: "untouched\n", +} + +// Shorthand for steps. +const A = "ses_A" +const B = "ses_B" +const C = "ses_C" +const ev = (type, payload = {}) => ["event", type, payload] +const asked = (sessionID) => ev("permission.asked", { sessionID }) +const replied = (sessionID) => ev("permission.replied", { sessionID }) +const idle = (sessionID) => ev("session.idle", { sessionID }) +const failed = (sessionID) => ev("session.error", { sessionID, error: { name: "ProviderError" } }) +const status = (sessionID, type) => ev("session.status", { sessionID, status: { type } }) +const times = (n, steps) => Array.from({ length: n }, () => steps).flat() + +// Options: +// opencode 1 (default) or 2: which plugin entry point the fake OpenCode calls +// service "up" (default), "down", or "none" for no CLI installed at all +// steps see driver.mjs +// reports what the service accepted, in order. Everything must have arrived by the +// time the process ends. +// declined how many reports the CLI was given while the service was down +// A report that is sent twice keeps its request_id, and the real service applies it once. +// Both lists count it once too. +// leds what each ["led"] step saw +// led what LEDS.LED holds at the end. Defaults to "untouched" when the service is up. +// keepalive what each ["beat"] step saw: true when the file was touched +// volume name of the device folder (default "SidePulse"), or null for no device +// ledFile false: the device folder has no LEDS.LED +// cli where the CLI is found: "env" (default), "home", "path" +// decoy put a wrong CLI at "home" or "path". It must never run. +// hang the CLI never answers +// env extra environment for the plugin +// check a function given { bodies, result } for anything else +const tests = [] +const test = (name, options) => tests.push({ name, ...options }) + +// ---------------------------------------------------------------- app mode + +test("a turn reports working, blocked, working, done", { + steps: [["prompt", A], ["before", A, "bash"], asked(A), replied(A), ["after", A, "bash"], idle(A)], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A working", "ses_A done"], +}) + +test("tool calls start no process", { + steps: [["prompt", A], ...times(10, [["before", A, "bash"], ["after", A, "read"]]), idle(A)], + reports: ["ses_A working", "ses_A done"], +}) + +test("the question tool reports a question, then work", { + steps: [["prompt", A], ["before", A, "question"], ["after", A, "question"], idle(A)], + reports: ["ses_A working", "ses_A blocked/question", "ses_A working", "ses_A done"], +}) + +test("a prompt holds its own session through tool calls, and no other", { + steps: [ + ["prompt", A], + asked(A), + ["after", A, "bash"], + ["before", A, "bash"], + ["prompt", B], + ["after", B, "bash"], + ["before", B, "bash"], + replied(A), + idle(A), + idle(B), + ], + reports: ["ses_A working", "ses_A blocked/permission", "ses_B working", "ses_A working", "ses_A done", "ses_B done"], +}) + +test("a provider retry reports an error with a reason, then recovers", { + steps: [ + ["prompt", A], + ev("session.status", { sessionID: A, status: { type: "busy" } }), + ev("session.status", { sessionID: A, status: { type: "retry" } }), + ev("session.status", { sessionID: A, status: { type: "retry" } }), + ev("session.status", { sessionID: A, status: { type: "busy" } }), + ev("session.status", { sessionID: A, status: { type: "busy" } }), + idle(A), + ], + reports: ["ses_A working", "ses_A error (Retrying a failed provider call)", "ses_A working", "ses_A done"], +}) + +test("a busy status resumes only after a retry", { + steps: [ + ["prompt", A], + asked(A), + status(A, "busy"), + replied(A), + status(A, "retry"), + status(A, "busy"), + // The retry is over. A later busy status must not answer a prompt. + asked(A), + status(A, "busy"), + replied(A), + // A new turn ends a retry too. + status(A, "retry"), + ["prompt", A], + asked(A), + status(A, "busy"), + // And so does the end of the turn. + status(A, "retry"), + idle(A), + asked(A), + status(A, "busy"), + idle(A), + ], + reports: [ + "ses_A working", + "ses_A blocked/permission", + "ses_A working", + "ses_A error (Retrying a failed provider call)", + "ses_A working", + "ses_A blocked/permission", + "ses_A working", + "ses_A error (Retrying a failed provider call)", + "ses_A working", + "ses_A blocked/permission", + "ses_A error (Retrying a failed provider call)", + "ses_A done", + "ses_A blocked/permission", + "ses_A done", + ], +}) + +test("a retry that ends the turn does not report work first", { + steps: [["prompt", A], status(A, "retry"), status(A, "idle"), idle(A)], + reports: ["ses_A working", "ses_A error (Retrying a failed provider call)", "ses_A done"], +}) + +test("a question after a permission prompt changes the kind", { + steps: [["prompt", A], asked(A), ["before", A, "question"], ["after", A, "question"], idle(A)], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A blocked/question", "ses_A working", "ses_A done"], +}) + +test("events before the first prompt report nothing", { + steps: [["before", A, "bash"], ["after", A, "bash"], status(A, "busy"), ev("session.status", { sessionID: A })], + reports: [], +}) + +test("a turn that ends while a prompt is open reports done", { + steps: [["prompt", A], ev("permission.updated", { sessionID: A }), idle(A)], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A done"], +}) + +test("a tool call after the turn ended reports nothing", { + steps: [["prompt", A], idle(A), ["after", A, "bash"], ["before", A, "bash"], ["before", A, "question"]], + reports: ["ses_A working", "ses_A done"], +}) + +test("an event without a session id reports under unknown", { + steps: [ev("permission.asked", {}), ev("session.idle", {})], + reports: ["unknown blocked/permission", "unknown done"], +}) + +test("an event the plugin does not know reports nothing", { + steps: [ + ["prompt", A], + ev("message.updated", { sessionID: A, status: { type: "retry" } }), + ev("session.created", { sessionID: A }), + idle(A), + ], + reports: ["ses_A working", "ses_A done"], +}) + +test("a report carries identity and state, and nothing else", { + steps: [["prompt", A], asked(A)], + check({ bodies }) { + const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/ + const ids = bodies.map((body) => body.request_id) + for (const id of ids) if (!uuid.test(id)) return `request_id ${id} is not a UUID` + if (new Set(ids).size !== ids.length) return "request_ids repeat" + const want = [ + { + v: 1, + type: "program_status", + scope: "opencode-ses_A", + status: { state: "working", app: "opencode" }, + context: { provider: "opencode", session_id: "ses_A", cwd: "/projects/demo" }, + }, + { + v: 1, + type: "program_status", + scope: "opencode-ses_A", + status: { state: "blocked", kind: "permission", app: "opencode" }, + context: { provider: "opencode", session_id: "ses_A", cwd: "/projects/demo" }, + }, + // The session is still blocked when the driver unloads, so the exit hook clears it. + { + v: 1, + type: "program_status", + scope: "opencode-ses_A", + status: { state: "clear", app: "opencode" }, + context: { provider: "opencode", session_id: "ses_A" }, + }, + ] + const got = bodies.map(({ request_id, ...rest }) => rest) + if (!isDeepStrictEqual(got, want)) return `bodies differ:\n${JSON.stringify(got, null, 2)}` + }, +}) + +// ----------------------------------------------------------- recorded traces +// +// Event sequences recorded from real OpenCode releases with a logging probe. Events the +// plugin ignores are thinned out, but at least one of each kind stays in. +// test/opencode.mjs runs the same turns live. + +test("OpenCode 1: cancel with ctrl+g ends like a finished turn", { + steps: [ + ["prompt", A], + ev("session.error", { sessionID: A, error: { name: "MessageAbortedError" } }), + idle(A), + idle(A), + ], + reports: ["ses_A working", "ses_A done"], +}) + +test("OpenCode 1.19.5: a turn that runs a tool", { + steps: [ + ev("session.created", { sessionID: A }), + ["prompt", A], + ev("message.updated", { sessionID: A }), + status(A, "busy"), + ev("plugin.added", {}), + ev("catalog.updated", {}), + status(A, "busy"), + ["before", A, "bash"], + ["after", A, "bash"], + status(A, "busy"), + status(A, "idle"), + idle(A), + ev("catalog.updated", {}), + ], + reports: ["ses_A working", "ses_A done"], +}) + +// OpenCode 1 sends session.idle after session.error. The turn failed, so it must not end +// green. +const failedTurnOnOpenCode1 = [ + ev("session.created", { sessionID: A }), + ["prompt", A], + status(A, "busy"), + ev("session.error", { sessionID: A, error: { name: "UnknownError", data: { message: "Model not found" } } }), + status(A, "idle"), + idle(A), +] + +test("OpenCode 1.19.5: a failed turn stays an error", { + steps: failedTurnOnOpenCode1, + reports: ["ses_A working", "ses_A error"], +}) + +test("OpenCode 1.19.5: a failed turn stays red on the device", { + service: "none", + steps: [...failedTurnOnOpenCode1, ["led"], idle(B), ["led"], ["prompt", A], idle(A)], + // Another session finishing still shows, and the next turn in the failed session starts clean. + leds: ["error", "done"], + led: "done", +}) + +test("OpenCode 1: an error without a name is still an error", { + steps: [["prompt", A], ev("session.error", { sessionID: A })], + reports: ["ses_A working", "ses_A error"], +}) + +test("OpenCode 1: a session works again after a failed turn", { + steps: [...failedTurnOnOpenCode1, ["prompt", A], idle(A), failed(A), ["after", A, "bash"], idle(A)], + reports: ["ses_A working", "ses_A error", "ses_A working", "ses_A done", "ses_A error"], +}) + +test("OpenCode 2: a turn reports working, blocked, working, done", { + opencode: 2, + steps: [ + ["prompt", A], + ev("session.execution.started", { sessionID: A }), + ["before", A, "bash"], + asked(A), + replied(A), + ["after", A, "bash"], + ev("session.execution.succeeded", { sessionID: A }), + ], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A working", "ses_A done"], +}) + +test("OpenCode 2.1.2: a cancelled turn ends like a finished turn", { + opencode: 2, + steps: [ + ["prompt", A], + ev("session.execution.started", { sessionID: A }), + ev("session.execution.interrupted", { sessionID: A, reason: "user" }), + ], + reports: ["ses_A working", "ses_A done"], +}) + +test("OpenCode 2.3.0: a turn that runs a tool", { + opencode: 2, + steps: [ + ["prompt", A], + ev("provider.updated", {}), + ev("session.inbox.enqueued", { sessionID: A }), + ev("session.execution.started", { sessionID: A }), + ev("session.renamed", { sessionID: A }), + ev("session.step.started", { sessionID: A }), + ev("session.tool.called", { sessionID: A }), + ["before", A, "shell"], + ev("shell.created", {}), + ev("session.tool.progress", { sessionID: A }), + ev("shell.exited", {}), + ["after", A, "shell"], + ev("session.tool.success", { sessionID: A }), + ev("session.step.ended", { sessionID: A }), + ev("session.text.delta", { sessionID: A }), + ev("session.execution.succeeded", { sessionID: A }), + ev("location.shutdown", {}), + ], + reports: ["ses_A working", "ses_A done"], +}) + +test("OpenCode 2.3.0: a failed turn reports an error", { + opencode: 2, + steps: [ + ["prompt", A], + ev("session.inbox.enqueued", { sessionID: A }), + ev("session.execution.started", { sessionID: A }), + ev("session.execution.failed", { sessionID: A, error: { type: "provider.no-route", message: "Model unavailable" } }), + ev("location.shutdown", {}), + ], + reports: ["ses_A working", "ses_A error"], +}) + +test("OpenCode 2: the question tool and a snake_case session id", { + opencode: 2, + steps: [["prompt", A], ["before", A, "question"], ["after", A, "question"], ev("permission.asked", { session_id: B })], + reports: ["ses_A working", "ses_A blocked/question", "ses_A working", "ses_B blocked/permission", "ses_A clear", "ses_B clear"], +}) + +test("OpenCode 2: unloading the plugin stops the event stream", { + opencode: 2, + steps: [["prompt", A], ev("session.execution.succeeded", { sessionID: A }), ["dispose"], asked(A)], + reports: ["ses_A working", "ses_A done"], +}) + +test("OpenCode 2: reports carry the project directory", { + opencode: 2, + steps: [["prompt", A], ev("session.execution.succeeded", { sessionID: A })], + check({ bodies, result }) { + if (bodies[0]?.context.cwd !== "/projects/demo") return `cwd is ${bodies[0]?.context.cwd}` + if (result.id !== "opencode-sidepulse") return `the plugin id is ${result.id}` + }, +}) + +// ------------------------------------------------------------ finding the CLI + +test("the CLI is found in ~/.local/bin when SIDEPULSE_BIN is not set", { + cli: "home", + decoy: "path", + steps: [["prompt", A], idle(A)], + reports: ["ses_A working", "ses_A done"], +}) + +test("the CLI is found on PATH when it is nowhere else", { + cli: "path", + steps: [["prompt", A], idle(A)], + reports: ["ses_A working", "ses_A done"], +}) + +test("SIDEPULSE_BIN wins over ~/.local/bin", { + cli: "env", + decoy: "home", + steps: [["prompt", A], idle(A)], + reports: ["ses_A working", "ses_A done"], +}) + +// -------------------------------------------------------------- direct mode + +const turnOnTheDevice = [ + ["prompt", A], + ["led"], + asked(A), + ["led"], + ["after", A, "bash"], + ["led"], + ["before", A, "bash"], + ["led"], + replied(A), + ["led"], + failed(A), + ["led"], + ["prompt", A], + ["led"], + idle(A), + ["led"], +] +const turnOnTheDeviceLeds = ["busy", "waiting", "waiting", "busy", "busy", "error", "busy", "done"] + +test("no CLI: every state is written to the device", { + service: "none", + steps: turnOnTheDevice, + leds: turnOnTheDeviceLeds, + reports: [], + led: "done", +}) + +test("service down: every state is written to the device", { + service: "down", + steps: turnOnTheDevice, + leds: turnOnTheDeviceLeds, + reports: [], + led: "done", +}) + +test("service down: tool calls start no process", { + service: "down", + steps: [["prompt", A], ...times(10, [["before", A, "bash"], ["after", A, "read"]]), ["led"], idle(A)], + leds: ["busy"], + declined: 2, + led: "done", +}) + +test("service down: a second session in the same state starts no process", { + service: "down", + steps: [["prompt", A], ["prompt", B], ["prompt", C]], + declined: 1, + led: "busy", +}) + +test("direct mode: a retry shows as an error, then recovers", { + service: "none", + steps: [ + ["prompt", A], + ev("session.status", { sessionID: A, status: { type: "retry" } }), + ["led"], + ev("session.status", { sessionID: A, status: { type: "busy" } }), + ["led"], + ], + leds: ["error", "busy"], + led: "busy", +}) + +test("direct mode: the question tool shows as waiting, then busy", { + service: "none", + steps: [["prompt", A], ["before", A, "question"], ["led"], ["after", A, "question"], ["led"]], + leds: ["waiting", "busy"], + led: "busy", +}) + +test("direct mode: a prompt outranks a tool finishing in any session", { + service: "none", + steps: [["prompt", A], asked(A), ["after", B, "bash"], ["led"], ["prompt", B], ["led"]], + leds: ["waiting", "busy"], + led: "busy", +}) + +test("direct mode: a new turn forgets the last prompt", { + service: "none", + steps: [["prompt", A], asked(A), ["prompt", A], ["after", A, "bash"], ["led"]], + leds: ["busy"], + led: "busy", +}) + +test("direct mode: a tool call outside a turn does not repaint", { + service: "none", + steps: [asked(A), ["before", A, "bash"], ["led"]], + leds: ["waiting"], + led: "waiting", +}) + +test("direct mode: a tool call after the turn ended does not repaint", { + service: "none", + steps: [["prompt", A], idle(A), ["after", A, "bash"], ["before", A, "bash"]], + led: "done", +}) + +test("direct mode: an unchanged state is not written again", { + service: "none", + steps: [["prompt", A], ["write-led", "someone else\n"], ["before", A, "bash"], ["after", A, "bash"]], + led: "someone else\n", +}) + +test("direct mode: no device is not an error", { + service: "none", + volume: null, + steps: [["prompt", A], asked(A), idle(A), ["led"], ["beat"]], + leds: [null], + keepalive: [null], + led: null, +}) + +test("direct mode: a device that appears later is painted on the next event", { + service: "none", + ledFile: false, + steps: [["prompt", A], ["led"], ["write-led", "fresh\n"], ["before", A, "bash"], ["led"]], + leds: [null, "busy"], + led: "busy", +}) + +for (const volume of ["SidePulsePro", "PulseDot", "sidepulse lower"]) + test(`direct mode: the volume ${volume} is a device`, { + service: "none", + volume, + steps: [["prompt", A]], + led: "busy", + }) + +for (const volume of ["Macintosh HD", "My SidePulse"]) + test(`direct mode: the volume ${volume} is not a device`, { + service: "none", + volume, + steps: [["prompt", A]], + led: "untouched", + }) + +// ------------------------------------------------- moving between the modes + +test("the service takes the device over, and gives it back", { + service: "down", + steps: [ + ["prompt", A], + ["led"], + ["service", "up"], + asked(A), + ["write-led", "service owned\n"], + ["before", A, "bash"], + ["led"], + ["service", "down"], + replied(A), + ["led"], + idle(A), + ], + // The last "busy" matters: direct mode showed busy before the service took over, and it + // must paint busy again afterwards instead of assuming the device still shows it. + leds: ["busy", "service owned\n", "busy"], + reports: ["ses_A blocked/permission"], + led: "done", +}) + +test("a report the service declines is sent again when the state returns", { + service: "down", + steps: [["prompt", A], asked(A), ["service", "up"], replied(A), idle(A)], + reports: ["ses_A working", "ses_A done"], + declined: 2, +}) + +test("a CLI that never answers falls back to the device", { + hang: true, + env: { SIDEPULSE_REPORT_TIMEOUT_MS: "150" }, + steps: [["prompt", A], ["led"]], + leds: ["busy"], + reports: [], + led: "busy", +}) + +// ------------------------------------------------------------- keepalive + +test("keepalive: direct mode touches the file", { + service: "none", + steps: [["beat"]], + keepalive: [true], + led: "untouched", +}) + +test("keepalive: the service owns it in app mode", { + steps: [["prompt", A], idle(A), ["beat"]], + keepalive: [false], +}) + +// ------------------------------------------------------------------ order + +test("a slow report is not overtaken by the ones behind it", { + steps: [["delay", 0.3], ["fast", [["prompt", A], asked(A), idle(A)]], ["drain"]], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A done"], +}) + +test("hooks do not wait for the CLI", { + steps: [["delay", 0.8], ["fast", [["prompt", A], ["led"]]], idle(A)], + check({ result }) { + if (result.elapsedToFirstLed > 500) return `the hook took ${result.elapsedToFirstLed} ms to return` + }, + reports: ["ses_A working", "ses_A done"], +}) + +// ------------------------------------------------------------------- exit + +test("exit: queued reports are sent, in order, before the process ends", { + steps: [["delay", 0.3], ["fast", [["prompt", A], asked(A), idle(A)]], ["exit"]], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A done"], +}) + +test("exit: a session still working is cleared", { + steps: [["prompt", A], ["exit"]], + reports: ["ses_A working", "ses_A clear"], +}) + +test("exit: a session still waiting is cleared", { + steps: [["prompt", A], asked(A), ["exit"]], + reports: ["ses_A working", "ses_A blocked/permission", "ses_A clear"], +}) + +test("exit: done and error stay, working is cleared", { + steps: [["prompt", A], idle(A), ["prompt", B], failed(B), ["prompt", C], ["exit"]], + reports: ["ses_A working", "ses_A done", "ses_B working", "ses_B error", "ses_C working", "ses_C clear"], +}) + +test("exit: a report still in flight is sent again, then cleared", { + steps: [["delay", 0.3], ["fast", [["prompt", A]]], ["exit"]], + reports: ["ses_A working", "ses_A clear"], +}) + +test("exit: a finished turn still in flight arrives before the process ends", { + steps: [["prompt", A], ["delay", 0.3], ["fast", [idle(A)]], ["exit"]], + reports: ["ses_A working", "ses_A done"], +}) + +test("exit: direct mode starts no process to clear sessions", { + service: "down", + steps: [["prompt", A], ["prompt", B], asked(B), ["exit"]], + reports: [], + declined: 2, + led: "waiting", +}) + +test("exit: queued reports fall back to the device when the service is down", { + service: "down", + steps: [["delay", 0.3], ["fast", [["prompt", A], idle(A)]], ["exit"]], + reports: [], + declined: 2, + led: "done", +}) + +test("exit: a service that stopped is asked once, not once per session", { + steps: [["prompt", A], ["prompt", B], ["service", "down"], ["exit"]], + reports: ["ses_A working", "ses_B working"], + declined: 1, +}) + +// ------------------------------------------------------------------ runner + +const compact = (body) => { + const { state, kind, msg } = body.status + return `${body.scope.replace(/^opencode-/, "")} ${state}${kind ? `/${kind}` : ""}${msg ? ` (${msg})` : ""}` +} + +const lines = (file) => + existsSync(file) + ? readFileSync(file, "utf8") + .split("\n") + .filter(Boolean) + .map((line) => JSON.parse(line)) + : [] + +const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) + +function script(dir, name, body) { + mkdirSync(dir, { recursive: true }) + const file = join(dir, name) + if (body) writeFileSync(file, body) + else copyFileSync(FAKE_CLI, file) + chmodSync(file, 0o755) + return file +} + +async function run(t) { + const dir = mkdtempSync(join(tmpdir(), "opencode-sidepulse-")) + const fake = join(dir, "fake") + const home = join(dir, "home") + const bin = join(dir, "bin") + const volumes = join(dir, "volumes") + for (const made of [fake, home, bin, volumes]) mkdirSync(made) + + const service = t.service ?? "up" + if (service === "up") writeFileSync(join(fake, "up"), "") + if (t.hang) writeFileSync(join(fake, "hang"), "") + + const volume = t.volume === undefined ? "SidePulse" : t.volume + const led = join(volumes, volume ?? "none", "LEDS.LED") + if (volume) { + mkdirSync(join(volumes, volume)) + if (t.ledFile !== false) writeFileSync(led, LED.untouched) + const keepalive = join(volumes, volume, "keepalive") + writeFileSync(keepalive, "") + const old = new Date(Date.now() - 3_600_000) + utimesSync(keepalive, old, old) + } + + // A decoy records that it ran. It answers 0 so a wrong lookup also loses the reports. + const decoy = `#!/bin/sh\ncat > /dev/null\n: > "${join(fake, "decoy-ran")}"\n` + const env = { ...process.env, ...t.env, HOME: home, SIDEPULSE_VOLUMES: volumes, FAKE_SIDEPULSE_DIR: fake } + delete env.SIDEPULSE_BIN + delete env.XDG_STATE_HOME + const cli = service === "none" ? "none" : (t.cli ?? "env") + if (cli === "none") env.SIDEPULSE_BIN = join(dir, "missing", "sidepulse") + if (cli === "env") env.SIDEPULSE_BIN = FAKE_CLI + if (cli === "home") script(join(home, ".local", "bin"), "sidepulse") + if (cli === "path") script(bin, "sidepulse") + if (t.decoy === "home") script(join(home, ".local", "bin"), "sidepulse", decoy) + if (t.decoy === "path") script(bin, "sidepulse", decoy) + env.PATH = `${bin}${delimiter}${process.env.PATH}` + env.SCENARIO = JSON.stringify({ opencode: t.opencode ?? 1, steps: t.steps }) + env.SCENARIO_DIR = dir + env.SCENARIO_LED = led + + const problems = [] + const child = spawn(process.execPath, [DRIVER], { env, stdio: ["ignore", "pipe", "pipe"] }) + let output = "" + child.stdout.on("data", (chunk) => (output += chunk)) + child.stderr.on("data", (chunk) => (output += chunk)) + const timer = setTimeout(() => child.kill("SIGKILL"), 30_000) + const code = await new Promise((resolve) => child.once("close", (status, signal) => resolve(signal ?? status))) + clearTimeout(timer) + if (code !== 0) problems.push(`the driver ended with ${code}\n${output.trim()}`) + + // Read at once. Anything the plugin owes the service must be there when the process + // ends. A detached copy of the last report may still arrive later. It repeats a + // request_id, so it would not change the lists below. + const once = (bodies) => { + const seen = new Set() + return bodies.filter((body) => !seen.has(body.request_id) && seen.add(body.request_id)) + } + const bodies = once(lines(join(fake, "reports.jsonl"))) + const declined = once(lines(join(fake, "declined.jsonl"))) + const result = existsSync(join(dir, "result.json")) ? JSON.parse(readFileSync(join(dir, "result.json"), "utf8")) : {} + const named = (value) => (value in LED ? LED[value] : value) + const expect = (what, got, want) => { + if (!isDeepStrictEqual(got, want)) + problems.push(`${what}\n want ${JSON.stringify(want)}\n got ${JSON.stringify(got)}`) + } + + if (t.reports) expect("reports the service applied", bodies.map(compact), t.reports) + if (t.declined !== undefined) expect("reports the stopped service was given", declined.length, t.declined) + if (t.leds) expect("LEDS.LED at each look", result.leds, t.leds.map(named)) + if (t.keepalive) expect("keepalive touched at each beat", result.keepalive, t.keepalive) + const wantLed = t.led === undefined ? (service === "up" && !t.hang ? "untouched" : undefined) : t.led + if (wantLed !== undefined) + expect("LEDS.LED at the end", existsSync(led) ? readFileSync(led, "utf8") : null, named(wantLed)) + if (existsSync(join(fake, "decoy-ran"))) problems.push("the wrong CLI was started") + const custom = t.check?.({ bodies, result }) + if (custom) problems.push(custom) + + if (problems.length && keep) problems.push(`files kept in ${dir}`) + else rmSync(dir, { recursive: true, force: true }) + return problems +} + +const keep = process.argv.includes("--keep") +const only = process.argv.slice(2).find((arg) => !arg.startsWith("--")) +const chosen = tests.filter((t) => !only || t.name.includes(only)) +const names = new Set() +for (const t of tests) { + if (names.has(t.name)) throw new Error(`two tests are named "${t.name}"`) + names.add(t.name) +} + +// Run a few at a time. Each test has its own folders, so they cannot disturb each other. +const outcomes = new Array(chosen.length) +let next = 0 +const workers = Array.from({ length: Math.min(availableParallelism(), 8) }, async () => { + while (next < chosen.length) { + const index = next++ + outcomes[index] = await run(chosen[index]).catch((error) => [String(error?.stack ?? error)]) + } +}) +await Promise.all(workers) + +let failures = 0 +chosen.forEach((t, index) => { + const problems = outcomes[index] + if (!problems.length) return console.log(`ok ${t.name}`) + failures++ + console.log(`FAILED ${t.name}`) + for (const problem of problems) console.log(` - ${problem}`) +}) +console.log(`\n${chosen.length - failures} of ${chosen.length} passed`) +if (failures || !chosen.length) process.exitCode = 1 diff --git a/test/service.mjs b/test/service.mjs new file mode 100644 index 0000000..4fa8a62 --- /dev/null +++ b/test/service.mjs @@ -0,0 +1,173 @@ +// Runs the plugin against a real SidePulse install. Use it to check a SidePulse version: +// +// SIDEPULSE_BIN=/path/to/sidepulse node test/service.mjs # a version with `sidepulse report` +// SIDEPULSE_BIN=/path/to/sidepulse node test/service.mjs --legacy # a version from before it +// +// The first form starts `sidepulse service run` in a throwaway home folder, drives the +// plugin through fake OpenCode hooks, and reads back what the service shows with +// `sidepulse status`. The second form checks that the plugin falls back to direct mode. +// CI runs both against pinned SidePulse commits and against its main branch. + +import { spawn, spawnSync } from "node:child_process" +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { fileURLToPath } from "node:url" +import { isDeepStrictEqual } from "node:util" + +const cli = process.env.SIDEPULSE_BIN +if (!cli || !existsSync(cli)) { + console.error("Set SIDEPULSE_BIN to a real sidepulse CLI.") + process.exit(2) +} +const legacy = process.argv.includes("--legacy") +const DRIVER = fileURLToPath(new URL("driver.mjs", import.meta.url)) +const UNTOUCHED = "untouched\n" +const BUSY = "off\n0:#00ccff 1:#0088cc 2:#004466 3:#001a26\nroll 1.2s linear\nrepeat\n" +const DONE = "#00ff22 0.6s cosine\n" + +const dir = mkdtempSync(join(tmpdir(), "opencode-sidepulse-service-")) +const home = join(dir, "home") +const led = join(dir, "volumes", "SidePulse", "LEDS.LED") +mkdirSync(home) +mkdirSync(join(dir, "volumes", "SidePulse"), { recursive: true }) +writeFileSync(led, UNTOUCHED) + +// The service and the CLI find each other through the home folder, so they share this one. +const env = { ...process.env, HOME: home, SIDEPULSE_BIN: cli, SIDEPULSE_VOLUMES: join(dir, "volumes") } +delete env.XDG_STATE_HOME +delete env.XDG_CONFIG_HOME + +const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) +const ev = (type, payload = {}) => ["event", type, payload] + +let failures = 0 +function check(name, got, want) { + if (isDeepStrictEqual(got, want)) return console.log(`ok ${name}`) + failures++ + console.log(`FAILED ${name}\n want ${JSON.stringify(want)}\n got ${JSON.stringify(got)}`) +} + +// What the service shows for the given sessions: mode, message and how many reports it applied. +function shown(...sessions) { + const { stdout } = spawnSync(cli, ["status", "--json", "--all"], { env, encoding: "utf8" }) + const snapshot = JSON.parse(stdout.split("\n")[0]) + const rows = [...snapshot.statuses, ...snapshot.stale_statuses] + return Object.fromEntries( + sessions.map((id) => { + const row = rows.find((candidate) => candidate.session_id === id) + return [id, row ? `${row.mode} after ${row.seq}` : "absent"] + }), + ) +} + +function drive(opencode, steps) { + const scenario = mkdtempSync(join(dir, "scenario-")) + const result = spawnSync(process.execPath, [DRIVER], { + env: { ...env, SCENARIO: JSON.stringify({ opencode, steps }), SCENARIO_DIR: scenario, SCENARIO_LED: led, FAKE_SIDEPULSE_DIR: scenario }, + encoding: "utf8", + timeout: 60_000, + }) + if (result.status !== 0) { + failures++ + console.log(`FAILED the driver ended with ${result.status ?? result.signal}\n${result.stdout}${result.stderr}`) + } + const file = join(scenario, "result.json") + return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : { status: [], leds: [] } +} + +if (legacy) { + // A SidePulse from before `sidepulse report`. The command fails, so the plugin must + // drive the device itself. + const probe = spawnSync(cli, ["report", "--json"], { env, input: "{}", encoding: "utf8" }) + check("this SidePulse has no report command", probe.status !== 0, true) + const result = drive(1, [["prompt", "old"], ["led"], ev("session.idle", { sessionID: "old" }), ["led"]]) + check("the plugin writes the device itself", result.leds, [BUSY, DONE]) +} else { + const service = spawn(cli, ["service", "run"], { env, stdio: ["ignore", "pipe", "pipe"] }) + let log = "" + service.stdout.on("data", (chunk) => (log += chunk)) + service.stderr.on("data", (chunk) => (log += chunk)) + const stopped = new Promise((resolve) => service.once("exit", resolve)) + try { + let up = false + for (let tries = 0; tries < 150 && !up && service.exitCode === null; tries++) { + up = spawnSync(cli, ["status", "--json"], { env }).status === 0 + if (!up) await sleep(200) + } + if (!up) throw new Error(`the service did not start\n${log}`) + + const a = drive(1, [ + ["prompt", "v1-a"], + ["status"], + ev("permission.asked", { sessionID: "v1-a" }), + ["prompt", "v1-b"], + ["after", "v1-b", "bash"], + ["status"], + ev("permission.replied", { sessionID: "v1-a" }), + ev("session.status", { sessionID: "v1-a", status: { type: "retry" } }), + ["status"], + ev("session.status", { sessionID: "v1-a", status: { type: "busy" } }), + ["status"], + ev("session.idle", { sessionID: "v1-a" }), + ev("session.error", { sessionID: "v1-b", error: { name: "ProviderError" } }), + ["status"], + ]) + check("OpenCode 1: what the service shows at each step", a.status, [ + { "v1-a": "working" }, + { "v1-a": "waiting_for_input", "v1-b": "working" }, + { "v1-a": "blocked_error (Retrying a failed provider call)", "v1-b": "working" }, + { "v1-a": "working", "v1-b": "working" }, + { "v1-a": "completed", "v1-b": "blocked_error" }, + ]) + check("OpenCode 1: done and error are kept after the plugin unloads", shown("v1-a", "v1-b"), { + "v1-a": "completed after 6", + "v1-b": "blocked_error after 2", + }) + + const b = drive(2, [ + ["prompt", "v2-a"], + ev("session.execution.started", { sessionID: "v2-a" }), + ["before", "v2-a", "question"], + ["status"], + ["after", "v2-a", "question"], + ["before", "v2-a", "bash"], + ["after", "v2-a", "bash"], + ["status"], + ev("session.execution.succeeded", { sessionID: "v2-a" }), + ["status"], + ]) + check( + "OpenCode 2: what the service shows at each step", + b.status.map((status) => status["v2-a"]), + ["waiting_for_input", "working", "completed"], + ) + + // The plugin sends the report in flight a second time when the process exits. The + // service must apply it once: three states, three applied reports. + drive(1, [["fast", [["prompt", "run"], ev("permission.asked", { sessionID: "run" }), ev("session.idle", { sessionID: "run" })]], ["exit"]]) + await sleep(1500) + check("exit: queued reports arrive in order and a repeat is applied once", shown("run"), { run: "completed after 3" }) + + drive(1, [["prompt", "quit-working"], ["prompt", "quit-waiting"], ev("permission.asked", { sessionID: "quit-waiting" }), ["exit"]]) + drive(1, [["fast", [["prompt", "quit-at-once"]]], ["exit"]]) + await sleep(1500) + check("exit: unfinished sessions are cleared", shown("quit-working", "quit-waiting", "quit-at-once"), { + "quit-working": "absent", + "quit-waiting": "absent", + "quit-at-once": "absent", + }) + + check("the plugin never wrote the device while the service ran", readFileSync(led, "utf8"), UNTOUCHED) + } finally { + service.kill() + await stopped + } + + const after = drive(1, [["prompt", "late"], ["led"], ev("session.idle", { sessionID: "late" }), ["led"]]) + check("service stopped: the plugin writes the device itself", after.leds, [BUSY, DONE]) +} + +if (failures) console.log(`\n${failures} failed. Files kept in ${dir}`) +else rmSync(dir, { recursive: true, force: true }) +process.exitCode = failures ? 1 : 0