An agentic skills framework & software development methodology that works.
Add design spec and tests for zero-dep brainstorm server
Jesse Vincent9c98e018732f
diff --git a/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md b/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.mdnew file mode 100644index 000000000..d92e89fb2--- /dev/null+++ b/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md@@ -0,0 +1,118 @@+# Zero-Dependency Brainstorm Server++Replace the brainstorm companion server's vendored node_modules (express, ws, chokidar — 714 tracked files) with a single zero-dependency `server.js` using only Node.js built-ins.++## Motivation++Vendoring node_modules into the git repo creates a supply chain risk: frozen dependencies don't get security patches, 714 files of third-party code are committed without audit, and modifications to vendored code look like normal commits. While the actual risk is low (localhost-only dev server), eliminating it is straightforward.++## Architecture++A single `server.js` file (~250-300 lines) using `http`, `crypto`, `fs`, and `path`. The file serves two roles:++- **When run directly** (`node server.js`): starts the HTTP/WebSocket server+- **When required** (`require('./server.js')`): exports WebSocket protocol functions for unit testing++### WebSocket Protocol++Implements RFC 6455 for text frames only:++**Handshake:** Compute `Sec-WebSocket-Accept` from client's `Sec-WebSocket-Key` using SHA-1 + the RFC 6455 magic GUID. Return 101 Switching Protocols.++**Frame decoding (client to server):** Handle three masked length encodings:+- Small: payload < 126 bytes+- Medium: 126-65535 bytes (16-bit extended)+- Large: > 65535 bytes (64-bit extended)++XOR-unmask payload using 4-byte mask key. Return `{ opcode, payload, bytesConsumed }` or `null` for incomplete buffers. Reject unmasked frames.++**Frame encoding (server to client):** Unmasked frames with the same three length encodings.++**Opcodes handled:** TEXT (0x01), CLOSE (0x08), PING (0x09), PONG (0x0A). Unrecognized opcodes get a close frame with status 1003 (Unsupported Data).++**Deliberately skipped:** Binary frames, fragmented messages, extensions (permessage-deflate), subprotocols. These are unnecessary for small JSON text messages between localhost clients. Extensions and subprotocols are negotiated in the handshake — by not advertising them, they are never active.++**Buffer accumulation:** Each connection maintains a buffer. On `data`, append and loop `decodeFrame` until it returns null or buffer is empty.++### HTTP Server++Three routes:++1. **`GET /`** — Serve newest `.html` from screen directory by mtime. Detect full documents vs fragments, wrap fragments in frame template, inject helper.js. Return `text/html`. When no `.html` files exist, serve a hardcoded waiting page ("Waiting for Claude to push a screen...") with helper.js injected.+2. **`GET /files/*`** — Serve static files from screen directory with MIME type lookup from a hardcoded extension map (html, css, js, png, jpg, gif, svg, json). Return 404 if not found.+3. **Everything else** — 404.++WebSocket upgrade handled via the `'upgrade'` event on the HTTP server, separate from the request handler.++### Configuration++Environment variables (all optional):++- `BRAINSTORM_PORT` — port to bind (default: random high port 49152-65535)+- `BRAINSTORM_HOST` — interface to bind (default: `127.0.0.1`)+- `BRAINSTORM_URL_HOST` — hostname for the URL in startup JSON (default: `localhost` when host is `127.0.0.1`, otherwise same as host)+- `BRAINSTORM_DIR` — screen directory path (default: `/tmp/brainstorm`)++### Startup Sequence++1. Create `SCREEN_DIR` if it doesn't exist (`mkdirSync` recursive)+2. Load frame template and helper.js from `__dirname`+3. Start HTTP server on configured host/port+4. Start `fs.watch` on `SCREEN_DIR`+5. On successful listen, log `server-started` JSON to stdout: `{ type, port, host, url_host, url, screen_dir }`+6. Write the same JSON to `SCREEN_DIR/.server-info` so agents can find connection details when stdout is hidden (background execution)++### Application-Level WebSocket Messages++When a TEXT frame arrives from a client:++1. Parse as JSON. If parsing fails, log to stderr and continue.+2. Log to stdout as `{ source: 'user-event', ...event }`.+3. If the event contains a `choice` property, append the JSON to `SCREEN_DIR/.events` (one line per event).++### File Watching++`fs.watch(SCREEN_DIR)` replaces chokidar. On HTML file events:++- On new file (`rename` event for a file that exists): delete `.events` file if present (`unlinkSync`), log `screen-added` to stdout as JSON+- On file change (`change` event): log `screen-updated` to stdout as JSON (do NOT clear `.events`)+- Both events: send `{ type: 'reload' }` to all connected WebSocket clients++Debounce per-filename with ~100ms timeout to prevent duplicate events (common on macOS and Linux).++### Error Handling++- Malformed JSON from WebSocket clients: log to stderr, continue+- Unhandled opcodes: close with status 1003+- Client disconnects: remove from broadcast set+- `fs.watch` errors: log to stderr, continue+- No graceful shutdown logic — shell scripts handle process lifecycle via SIGTERM++## What Changes++| Before | After |+|---|---|+| `index.js` + `package.json` + `package-lock.json` + 714 `node_modules` files | `server.js` (single file) |+| express, ws, chokidar dependencies | none |+| No static file serving | `/files/*` serves from screen directory |++## What Stays the Same++- `helper.js` — no changes+- `frame-template.html` — no changes+- `start-server.sh` — one-line update: `index.js` to `server.js`+- `stop-server.sh` — no changes+- `visual-companion.md` — no changes+- All existing server behavior and external contract++## Platform Compatibility++- `server.js` uses only cross-platform Node built-ins+- `fs.watch` is reliable for single flat directories on macOS, Linux, and Windows+- Shell scripts require bash (Git Bash on Windows, which is required for Claude Code)++## Testing++**Unit tests** (`ws-protocol.test.js`): Test WebSocket frame encoding/decoding, handshake computation, and protocol edge cases directly by requiring `server.js` exports.++**Integration tests** (`server.test.js`): Test full server behavior — HTTP serving, WebSocket communication, file watching, brainstorming workflow. Uses `ws` npm package as a test-only client dependency (not shipped to end users).diff --git a/tests/brainstorm-server/server.test.js b/tests/brainstorm-server/server.test.jsindex 85e72dabf..35a4ca556 100644--- a/tests/brainstorm-server/server.test.js+++ b/tests/brainstorm-server/server.test.js@@ -1,3 +1,13 @@+/**+ * Integration tests for the brainstorm server.+ *+ * Tests the full server behavior: HTTP serving, WebSocket communication,+ * file watching, and the brainstorming workflow.+ *+ * Uses the `ws` npm package as a test client (test-only dependency,+ * not shipped to end users).+ */+const { spawn } = require('child_process');const http = require('http');const WebSocket = require('ws');@@ -5,7 +15,7 @@ const fs = require('fs');const path = require('path');const assert = require('assert');-const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/index.js');+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.js');const TEST_PORT = 3334;const TEST_DIR = '/tmp/brainstorm-test';@@ -24,7 +34,11 @@ async function fetch(url) {http.get(url, (res) => {let data = '';res.on('data', chunk => data += chunk);- res.on('end', () => resolve({ status: res.statusCode, body: data }));+ res.on('end', () => resolve({+ status: res.statusCode,+ headers: res.headers,+ body: data+ }));}).on('error', reject);});}@@ -35,153 +49,371 @@ function startServer() {});}+async function waitForServer(server) {+ let stdout = '';+ let stderr = '';++ return new Promise((resolve, reject) => {+ server.stdout.on('data', (data) => {+ stdout += data.toString();+ if (stdout.includes('server-started')) {+ resolve({ stdout, stderr, getStdout: () => stdout });+ }+ });+ server.stderr.on('data', (data) => { stderr += data.toString(); });+ server.on('error', reject);++ setTimeout(() => reject(new Error(`Server didn't start. stderr: ${stderr}`)), 5000);+ });+}+async function runTests() {cleanup();fs.mkdirSync(TEST_DIR, { recursive: true });const server = startServer();+ let stdoutAccum = '';+ server.stdout.on('data', (data) => { stdoutAccum += data.toString(); });- let stdout = '';- let stderr = '';- server.stdout.on('data', (data) => { stdout += data.toString(); });- server.stderr.on('data', (data) => { stderr += data.toString(); });+ const { stdout: initialStdout } = await waitForServer(server);+ let passed = 0;+ let failed = 0;- // Wait for server to start (up to 3 seconds)- for (let i = 0; i < 30; i++) {- if (stdout.includes('server-started')) break;- await sleep(100);+ function test(name, fn) {+ return fn().then(() => {+ console.log(` PASS: ${name}`);+ passed++;+ }).catch(e => {+ console.log(` FAIL: ${name}`);+ console.log(` ${e.message}`);+ failed++;+ });}- if (stderr) console.error('Server stderr:', stderr);try {- // Test 1: Server starts and outputs JSON- console.log('Test 1: Server startup message');- assert(stdout.includes('server-started'), 'Should output server-started');- assert(stdout.includes(TEST_PORT.toString()), 'Should include port');- console.log(' PASS');-- // Test 2: GET / returns waiting page with helper injected when no screens exist- console.log('Test 2: Serves waiting page with helper injected');- const res = await fetch(`http://localhost:${TEST_PORT}/`);- assert.strictEqual(res.status, 200);- assert(res.body.includes('Waiting for Claude'), 'Should show waiting message');- assert(res.body.includes('WebSocket'), 'Should have helper.js injected');- console.log(' PASS');-- // Test 3: WebSocket connection and event relay- console.log('Test 3: WebSocket relays events to stdout');- stdout = '';- const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);- await new Promise(resolve => ws.on('open', resolve));-- ws.send(JSON.stringify({ type: 'click', text: 'Test Button' }));- await sleep(300);-- assert(stdout.includes('"source":"user-event"'), 'Should relay user events with source field');- assert(stdout.includes('Test Button'), 'Should include event data');- ws.close();- console.log(' PASS');-- // Test 4: File change triggers reload notification- console.log('Test 4: File change notifies browsers');- const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);- await new Promise(resolve => ws2.on('open', resolve));-- let gotReload = false;- ws2.on('message', (data) => {- const msg = JSON.parse(data.toString());- if (msg.type === 'reload') gotReload = true;- });-- fs.writeFileSync(path.join(TEST_DIR, 'test-screen.html'), '<html><body>Full doc</body></html>');- await sleep(500);-- assert(gotReload, 'Should send reload message on file change');- ws2.close();- console.log(' PASS');-- // Test: Choice events written to .events file- console.log('Test: Choice events written to .events file');- const ws3 = new WebSocket(`ws://localhost:${TEST_PORT}`);- await new Promise(resolve => ws3.on('open', resolve));-- ws3.send(JSON.stringify({ type: 'click', choice: 'a', text: 'Option A' }));- await sleep(300);-- const eventsFile = path.join(TEST_DIR, '.events');- assert(fs.existsSync(eventsFile), '.events file should exist after choice click');- const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');- const event = JSON.parse(lines[lines.length - 1]);- assert.strictEqual(event.choice, 'a', 'Event should contain choice');- assert.strictEqual(event.text, 'Option A', 'Event should contain text');- ws3.close();- console.log(' PASS');-- // Test: .events cleared on new screen- console.log('Test: .events cleared on new screen');- // .events file should still exist from previous test- assert(fs.existsSync(path.join(TEST_DIR, '.events')), '.events should exist before new screen');- fs.writeFileSync(path.join(TEST_DIR, 'new-screen.html'), '<h2>New screen</h2>');- await sleep(500);- assert(!fs.existsSync(path.join(TEST_DIR, '.events')), '.events should be cleared after new screen');- console.log(' PASS');-- // Test 5: Full HTML document served as-is (not wrapped)- console.log('Test 5: Full HTML document served without frame wrapping');- const fullDoc = '<!DOCTYPE html>\n<html><head><title>Custom</title></head><body><h1>Custom Page</h1></body></html>';- fs.writeFileSync(path.join(TEST_DIR, 'full-doc.html'), fullDoc);- await sleep(300);-- const fullRes = await fetch(`http://localhost:${TEST_PORT}/`);- assert(fullRes.body.includes('<h1>Custom Page</h1>'), 'Should contain original content');- assert(fullRes.body.includes('WebSocket'), 'Should still inject helper.js');- // Should NOT have the frame template's indicator bar- assert(!fullRes.body.includes('indicator-bar') || fullDoc.includes('indicator-bar'),- 'Should not wrap full documents in frame template');- console.log(' PASS');-- // Test 6: Bare HTML fragment gets wrapped in frame template- console.log('Test 6: Content fragment wrapped in frame template');- const fragment = '<h2>Pick a layout</h2>\n<p class="subtitle">Choose one</p>\n<div class="options"><div class="option" data-choice="a"><div class="letter">A</div><div class="content"><h3>Simple</h3></div></div></div>';- fs.writeFileSync(path.join(TEST_DIR, 'fragment.html'), fragment);- await sleep(300);-- const fragRes = await fetch(`http://localhost:${TEST_PORT}/`);- // Should have the frame template structure- assert(fragRes.body.includes('indicator-bar'), 'Fragment should get indicator bar from frame');- assert(!fragRes.body.includes('<!-- CONTENT -->'), 'Content placeholder should be replaced');- // Should have the original content inside- assert(fragRes.body.includes('Pick a layout'), 'Fragment content should be present');- assert(fragRes.body.includes('data-choice="a"'), 'Fragment content should be intact');- // Should have helper.js injected- assert(fragRes.body.includes('WebSocket'), 'Fragment should have helper.js injected');- console.log(' PASS');-- // Test 7: Helper.js includes toggleSelect and send functions- console.log('Test 7: Helper.js provides toggleSelect and send');- const helperContent = fs.readFileSync(- path.join(__dirname, '../../skills/brainstorming/scripts/helper.js'), 'utf-8'- );- assert(helperContent.includes('toggleSelect'), 'helper.js should define toggleSelect');- assert(helperContent.includes('sendEvent'), 'helper.js should define sendEvent');- assert(helperContent.includes('selectedChoice'), 'helper.js should track selectedChoice');- assert(helperContent.includes('brainstorm'), 'helper.js should expose brainstorm API');- assert(!helperContent.includes('sendToClaude'), 'helper.js should not contain sendToClaude');- console.log(' PASS');-- // Test 8: Indicator bar uses CSS variables (theme support)- console.log('Test 8: Indicator bar uses CSS variables');- const templateContent = fs.readFileSync(- path.join(__dirname, '../../skills/brainstorming/scripts/frame-template.html'), 'utf-8'- );- assert(templateContent.includes('indicator-bar'), 'Template should have indicator bar');- assert(templateContent.includes('indicator-text'), 'Template should have indicator text element');- console.log(' PASS');-- console.log('\nAll tests passed!');+ // ========== Server Startup ==========+ console.log('\n--- Server Startup ---');++ await test('outputs server-started JSON on startup', () => {+ const msg = JSON.parse(initialStdout.trim());+ assert.strictEqual(msg.type, 'server-started');+ assert.strictEqual(msg.port, TEST_PORT);+ assert(msg.url, 'Should include URL');+ assert(msg.screen_dir, 'Should include screen_dir');+ return Promise.resolve();+ });++ await test('writes .server-info file', () => {+ const infoPath = path.join(TEST_DIR, '.server-info');+ assert(fs.existsSync(infoPath), '.server-info should exist');+ const info = JSON.parse(fs.readFileSync(infoPath, 'utf-8').trim());+ assert.strictEqual(info.type, 'server-started');+ assert.strictEqual(info.port, TEST_PORT);+ return Promise.resolve();+ });++ // ========== HTTP Serving ==========+ console.log('\n--- HTTP Serving ---');++ await test('serves waiting page when no screens exist', async () => {+ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert.strictEqual(res.status, 200);+ assert(res.body.includes('Waiting for Claude'), 'Should show waiting message');+ });++ await test('injects helper.js into waiting page', async () => {+ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert(res.body.includes('WebSocket'), 'Should have helper.js injected');+ assert(res.body.includes('toggleSelect'), 'Should have toggleSelect from helper');+ assert(res.body.includes('brainstorm'), 'Should have brainstorm API from helper');+ });++ await test('returns Content-Type text/html', async () => {+ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert(res.headers['content-type'].includes('text/html'), 'Should be text/html');+ });++ await test('serves full HTML documents as-is (not wrapped)', async () => {+ const fullDoc = '<!DOCTYPE html>\n<html><head><title>Custom</title></head><body><h1>Custom Page</h1></body></html>';+ fs.writeFileSync(path.join(TEST_DIR, 'full-doc.html'), fullDoc);+ await sleep(300);++ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert(res.body.includes('<h1>Custom Page</h1>'), 'Should contain original content');+ assert(res.body.includes('WebSocket'), 'Should still inject helper.js');+ assert(!res.body.includes('indicator-bar'), 'Should NOT wrap in frame template');+ });++ await test('wraps content fragments in frame template', async () => {+ const fragment = '<h2>Pick a layout</h2>\n<div class="options"><div class="option" data-choice="a"><div class="letter">A</div></div></div>';+ fs.writeFileSync(path.join(TEST_DIR, 'fragment.html'), fragment);+ await sleep(300);++ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert(res.body.includes('indicator-bar'), 'Fragment should get indicator bar');+ assert(!res.body.includes('<!-- CONTENT -->'), 'Placeholder should be replaced');+ assert(res.body.includes('Pick a layout'), 'Fragment content should be present');+ assert(res.body.includes('data-choice="a"'), 'Fragment interactive elements intact');+ });++ await test('serves newest file by mtime', async () => {+ fs.writeFileSync(path.join(TEST_DIR, 'older.html'), '<h2>Older</h2>');+ await sleep(100);+ fs.writeFileSync(path.join(TEST_DIR, 'newer.html'), '<h2>Newer</h2>');+ await sleep(300);++ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert(res.body.includes('Newer'), 'Should serve newest file');+ });++ await test('ignores non-html files for serving', async () => {+ // Write a newer non-HTML file — should still serve newest .html+ fs.writeFileSync(path.join(TEST_DIR, 'data.json'), '{"not": "html"}');+ await sleep(300);++ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert(res.body.includes('Newer'), 'Should still serve newest HTML');+ assert(!res.body.includes('"not"'), 'Should not serve JSON');+ });++ await test('returns 404 for non-root paths', async () => {+ const res = await fetch(`http://localhost:${TEST_PORT}/other`);+ assert.strictEqual(res.status, 404);+ });++ // ========== WebSocket Communication ==========+ console.log('\n--- WebSocket Communication ---');++ await test('accepts WebSocket upgrade on /', async () => {+ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise((resolve, reject) => {+ ws.on('open', resolve);+ ws.on('error', reject);+ });+ ws.close();+ });++ await test('relays user events to stdout with source field', async () => {+ stdoutAccum = '';+ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ ws.send(JSON.stringify({ type: 'click', text: 'Test Button' }));+ await sleep(300);++ assert(stdoutAccum.includes('"source":"user-event"'), 'Should tag with source');+ assert(stdoutAccum.includes('Test Button'), 'Should include event data');+ ws.close();+ });++ await test('writes choice events to .events file', async () => {+ // Clean up events from prior tests+ const eventsFile = path.join(TEST_DIR, '.events');+ if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);++ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ ws.send(JSON.stringify({ type: 'click', choice: 'b', text: 'Option B' }));+ await sleep(300);++ assert(fs.existsSync(eventsFile), '.events should exist');+ const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');+ const event = JSON.parse(lines[lines.length - 1]);+ assert.strictEqual(event.choice, 'b');+ assert.strictEqual(event.text, 'Option B');+ ws.close();+ });++ await test('does NOT write non-choice events to .events file', async () => {+ const eventsFile = path.join(TEST_DIR, '.events');+ if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);++ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ ws.send(JSON.stringify({ type: 'hover', text: 'Something' }));+ await sleep(300);++ // Non-choice events should not create .events file+ assert(!fs.existsSync(eventsFile), '.events should not exist for non-choice events');+ ws.close();+ });++ await test('handles multiple concurrent WebSocket clients', async () => {+ const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);+ const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await Promise.all([+ new Promise(resolve => ws1.on('open', resolve)),+ new Promise(resolve => ws2.on('open', resolve))+ ]);++ let ws1Reload = false;+ let ws2Reload = false;+ ws1.on('message', (data) => {+ if (JSON.parse(data.toString()).type === 'reload') ws1Reload = true;+ });+ ws2.on('message', (data) => {+ if (JSON.parse(data.toString()).type === 'reload') ws2Reload = true;+ });++ fs.writeFileSync(path.join(TEST_DIR, 'multi-client.html'), '<h2>Multi</h2>');+ await sleep(500);++ assert(ws1Reload, 'Client 1 should receive reload');+ assert(ws2Reload, 'Client 2 should receive reload');+ ws1.close();+ ws2.close();+ });++ await test('cleans up closed clients from broadcast list', async () => {+ const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws1.on('open', resolve));+ ws1.close();+ await sleep(100);++ // This should not throw even though ws1 is closed+ fs.writeFileSync(path.join(TEST_DIR, 'after-close.html'), '<h2>After</h2>');+ await sleep(300);+ // If we got here without error, the test passes+ });++ await test('handles malformed JSON from client gracefully', async () => {+ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ // Send invalid JSON — server should not crash+ ws.send('not json at all {{{');+ await sleep(300);++ // Verify server is still responsive+ const res = await fetch(`http://localhost:${TEST_PORT}/`);+ assert.strictEqual(res.status, 200, 'Server should still be running');+ ws.close();+ });++ // ========== File Watching ==========+ console.log('\n--- File Watching ---');++ await test('sends reload on new .html file', async () => {+ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ let gotReload = false;+ ws.on('message', (data) => {+ if (JSON.parse(data.toString()).type === 'reload') gotReload = true;+ });++ fs.writeFileSync(path.join(TEST_DIR, 'watch-new.html'), '<h2>New</h2>');+ await sleep(500);++ assert(gotReload, 'Should send reload on new file');+ ws.close();+ });++ await test('sends reload on .html file change', async () => {+ const filePath = path.join(TEST_DIR, 'watch-change.html');+ fs.writeFileSync(filePath, '<h2>Original</h2>');+ await sleep(500);++ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ let gotReload = false;+ ws.on('message', (data) => {+ if (JSON.parse(data.toString()).type === 'reload') gotReload = true;+ });++ fs.writeFileSync(filePath, '<h2>Modified</h2>');+ await sleep(500);++ assert(gotReload, 'Should send reload on file change');+ ws.close();+ });++ await test('does NOT send reload for non-.html files', async () => {+ const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);+ await new Promise(resolve => ws.on('open', resolve));++ let gotReload = false;+ ws.on('message', (data) => {+ if (JSON.parse(data.toString()).type === 'reload') gotReload = true;+ });++ fs.writeFileSync(path.join(TEST_DIR, 'data.txt'), 'not html');+ await sleep(500);++ assert(!gotReload, 'Should NOT reload for non-HTML files');+ ws.close();+ });++ await test('clears .events on new screen', async () => {+ // Create an .events file+ const eventsFile = path.join(TEST_DIR, '.events');+ fs.writeFileSync(eventsFile, '{"choice":"a"}\n');+ assert(fs.existsSync(eventsFile));++ fs.writeFileSync(path.join(TEST_DIR, 'clear-events.html'), '<h2>New screen</h2>');+ await sleep(500);++ assert(!fs.existsSync(eventsFile), '.events should be cleared on new screen');+ });++ await test('logs screen-added on new file', async () => {+ stdoutAccum = '';+ fs.writeFileSync(path.join(TEST_DIR, 'log-test.html'), '<h2>Log</h2>');+ await sleep(500);++ assert(stdoutAccum.includes('screen-added'), 'Should log screen-added');+ });++ await test('logs screen-updated on file change', async () => {+ const filePath = path.join(TEST_DIR, 'log-update.html');+ fs.writeFileSync(filePath, '<h2>V1</h2>');+ await sleep(500);++ stdoutAccum = '';+ fs.writeFileSync(filePath, '<h2>V2</h2>');+ await sleep(500);++ assert(stdoutAccum.includes('screen-updated'), 'Should log screen-updated');+ });++ // ========== Helper.js Content ==========+ console.log('\n--- Helper.js Verification ---');++ await test('helper.js defines required APIs', () => {+ const helperContent = fs.readFileSync(+ path.join(__dirname, '../../skills/brainstorming/scripts/helper.js'), 'utf-8'+ );+ assert(helperContent.includes('toggleSelect'), 'Should define toggleSelect');+ assert(helperContent.includes('sendEvent'), 'Should define sendEvent');+ assert(helperContent.includes('selectedChoice'), 'Should track selectedChoice');+ assert(helperContent.includes('brainstorm'), 'Should expose brainstorm API');+ return Promise.resolve();+ });++ // ========== Frame Template ==========+ console.log('\n--- Frame Template Verification ---');++ await test('frame template has required structure', () => {+ const template = fs.readFileSync(+ path.join(__dirname, '../../skills/brainstorming/scripts/frame-template.html'), 'utf-8'+ );+ assert(template.includes('indicator-bar'), 'Should have indicator bar');+ assert(template.includes('indicator-text'), 'Should have indicator text');+ assert(template.includes('<!-- CONTENT -->'), 'Should have content placeholder');+ assert(template.includes('claude-content'), 'Should have content container');+ return Promise.resolve();+ });++ // ========== Summary ==========+ console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);+ if (failed > 0) process.exit(1);} finally {server.kill();+ await sleep(100);cleanup();}}diff --git a/tests/brainstorm-server/ws-protocol.test.js b/tests/brainstorm-server/ws-protocol.test.jsnew file mode 100644index 000000000..ca505fa62--- /dev/null+++ b/tests/brainstorm-server/ws-protocol.test.js@@ -0,0 +1,392 @@+/**+ * Unit tests for the zero-dependency WebSocket protocol implementation.+ *+ * Tests the WebSocket frame encoding/decoding, handshake computation,+ * and protocol-level behavior independent of the HTTP server.+ *+ * The module under test exports:+ * - computeAcceptKey(clientKey) -> string+ * - encodeFrame(opcode, payload) -> Buffer+ * - decodeFrame(buffer) -> { opcode, payload, bytesConsumed } | null+ * - OPCODES: { TEXT, CLOSE, PING, PONG }+ */++const assert = require('assert');+const crypto = require('crypto');+const path = require('path');++// The module under test — will be the new zero-dep server file+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.js');+let ws;++try {+ ws = require(SERVER_PATH);+} catch (e) {+ // Module doesn't exist yet (TDD — tests written before implementation)+ console.error(`Cannot load ${SERVER_PATH}: ${e.message}`);+ console.error('This is expected if running tests before implementation.');+ process.exit(1);+}++function runTests() {+ let passed = 0;+ let failed = 0;++ function test(name, fn) {+ try {+ fn();+ console.log(` PASS: ${name}`);+ passed++;+ } catch (e) {+ console.log(` FAIL: ${name}`);+ console.log(` ${e.message}`);+ failed++;+ }+ }++ // ========== Handshake ==========+ console.log('\n--- WebSocket Handshake ---');++ test('computeAcceptKey produces correct RFC 6455 accept value', () => {+ // RFC 6455 Section 4.2.2 example+ // The magic GUID is "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"+ const clientKey = 'dGhlIHNhbXBsZSBub25jZQ==';+ const expected = 's3pPLMBiTxaQ9kYGzzhZRbK+xOo=';+ assert.strictEqual(ws.computeAcceptKey(clientKey), expected);+ });++ test('computeAcceptKey produces valid base64 for random keys', () => {+ for (let i = 0; i < 10; i++) {+ const randomKey = crypto.randomBytes(16).toString('base64');+ const result = ws.computeAcceptKey(randomKey);+ // Result should be valid base64+ assert.strictEqual(Buffer.from(result, 'base64').toString('base64'), result);+ // SHA-1 output is 20 bytes, base64 encoded = 28 chars+ assert.strictEqual(result.length, 28);+ }+ });++ // ========== Frame Encoding ==========+ console.log('\n--- Frame Encoding (server -> client) ---');++ test('encodes small text frame (< 126 bytes)', () => {+ const payload = 'Hello';+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.from(payload));+ // FIN bit + TEXT opcode = 0x81, length = 5+ assert.strictEqual(frame[0], 0x81);+ assert.strictEqual(frame[1], 5);+ assert.strictEqual(frame.slice(2).toString(), 'Hello');+ assert.strictEqual(frame.length, 7);+ });++ test('encodes empty text frame', () => {+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.alloc(0));+ assert.strictEqual(frame[0], 0x81);+ assert.strictEqual(frame[1], 0);+ assert.strictEqual(frame.length, 2);+ });++ test('encodes medium text frame (126-65535 bytes)', () => {+ const payload = Buffer.alloc(200, 0x41); // 200 'A's+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);+ assert.strictEqual(frame[0], 0x81);+ assert.strictEqual(frame[1], 126); // extended length marker+ assert.strictEqual(frame.readUInt16BE(2), 200);+ assert.strictEqual(frame.slice(4).toString(), payload.toString());+ assert.strictEqual(frame.length, 204);+ });++ test('encodes frame at exactly 126 bytes (boundary)', () => {+ const payload = Buffer.alloc(126, 0x42);+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);+ assert.strictEqual(frame[1], 126); // extended length marker+ assert.strictEqual(frame.readUInt16BE(2), 126);+ assert.strictEqual(frame.length, 130);+ });++ test('encodes frame at exactly 125 bytes (max small)', () => {+ const payload = Buffer.alloc(125, 0x43);+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);+ assert.strictEqual(frame[1], 125);+ assert.strictEqual(frame.length, 127);+ });++ test('encodes large frame (> 65535 bytes)', () => {+ const payload = Buffer.alloc(70000, 0x44);+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);+ assert.strictEqual(frame[0], 0x81);+ assert.strictEqual(frame[1], 127); // 64-bit length marker+ // 8-byte extended length at offset 2+ const len = Number(frame.readBigUInt64BE(2));+ assert.strictEqual(len, 70000);+ assert.strictEqual(frame.length, 10 + 70000);+ });++ test('encodes close frame', () => {+ const frame = ws.encodeFrame(ws.OPCODES.CLOSE, Buffer.alloc(0));+ assert.strictEqual(frame[0], 0x88); // FIN + CLOSE+ assert.strictEqual(frame[1], 0);+ });++ test('encodes pong frame with payload', () => {+ const payload = Buffer.from('ping-data');+ const frame = ws.encodeFrame(ws.OPCODES.PONG, payload);+ assert.strictEqual(frame[0], 0x8A); // FIN + PONG+ assert.strictEqual(frame[1], payload.length);+ assert.strictEqual(frame.slice(2).toString(), 'ping-data');+ });++ test('server frames are never masked (per RFC 6455)', () => {+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.from('test'));+ // Bit 7 of byte 1 is the mask bit — must be 0 for server frames+ assert.strictEqual(frame[1] & 0x80, 0);+ });++ // ========== Frame Decoding ==========+ console.log('\n--- Frame Decoding (client -> server) ---');++ // Helper: create a masked client frame+ function makeClientFrame(opcode, payload, fin = true) {+ const buf = Buffer.from(payload);+ const mask = crypto.randomBytes(4);+ const masked = Buffer.alloc(buf.length);+ for (let i = 0; i < buf.length; i++) {+ masked[i] = buf[i] ^ mask[i % 4];+ }++ let header;+ const finBit = fin ? 0x80 : 0x00;+ if (buf.length < 126) {+ header = Buffer.alloc(6);+ header[0] = finBit | opcode;+ header[1] = 0x80 | buf.length; // mask bit set+ mask.copy(header, 2);+ } else if (buf.length < 65536) {+ header = Buffer.alloc(8);+ header[0] = finBit | opcode;+ header[1] = 0x80 | 126;+ header.writeUInt16BE(buf.length, 2);+ mask.copy(header, 4);+ } else {+ header = Buffer.alloc(14);+ header[0] = finBit | opcode;+ header[1] = 0x80 | 127;+ header.writeBigUInt64BE(BigInt(buf.length), 2);+ mask.copy(header, 10);+ }++ return Buffer.concat([header, masked]);+ }++ test('decodes small masked text frame', () => {+ const frame = makeClientFrame(0x01, 'Hello');+ const result = ws.decodeFrame(frame);+ assert(result, 'Should return a result');+ assert.strictEqual(result.opcode, ws.OPCODES.TEXT);+ assert.strictEqual(result.payload.toString(), 'Hello');+ assert.strictEqual(result.bytesConsumed, frame.length);+ });++ test('decodes empty masked text frame', () => {+ const frame = makeClientFrame(0x01, '');+ const result = ws.decodeFrame(frame);+ assert(result, 'Should return a result');+ assert.strictEqual(result.opcode, ws.OPCODES.TEXT);+ assert.strictEqual(result.payload.length, 0);+ });++ test('decodes medium masked text frame (126-65535 bytes)', () => {+ const payload = 'A'.repeat(200);+ const frame = makeClientFrame(0x01, payload);+ const result = ws.decodeFrame(frame);+ assert(result, 'Should return a result');+ assert.strictEqual(result.payload.toString(), payload);+ });++ test('decodes large masked text frame (> 65535 bytes)', () => {+ const payload = 'B'.repeat(70000);+ const frame = makeClientFrame(0x01, payload);+ const result = ws.decodeFrame(frame);+ assert(result, 'Should return a result');+ assert.strictEqual(result.payload.length, 70000);+ assert.strictEqual(result.payload.toString(), payload);+ });++ test('decodes masked close frame', () => {+ const frame = makeClientFrame(0x08, '');+ const result = ws.decodeFrame(frame);+ assert(result, 'Should return a result');+ assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);+ });++ test('decodes masked ping frame', () => {+ const frame = makeClientFrame(0x09, 'ping!');+ const result = ws.decodeFrame(frame);+ assert(result, 'Should return a result');+ assert.strictEqual(result.opcode, ws.OPCODES.PING);+ assert.strictEqual(result.payload.toString(), 'ping!');+ });++ test('returns null for incomplete frame (not enough header bytes)', () => {+ const result = ws.decodeFrame(Buffer.from([0x81]));+ assert.strictEqual(result, null, 'Should return null for 1-byte buffer');+ });++ test('returns null for incomplete frame (header ok, payload truncated)', () => {+ // Create a valid frame then truncate it+ const frame = makeClientFrame(0x01, 'Hello World');+ const truncated = frame.slice(0, frame.length - 3);+ const result = ws.decodeFrame(truncated);+ assert.strictEqual(result, null, 'Should return null for truncated frame');+ });++ test('returns null for incomplete extended-length header', () => {+ // Frame claiming 16-bit length but only 3 bytes total+ const buf = Buffer.alloc(3);+ buf[0] = 0x81;+ buf[1] = 0x80 | 126; // masked, 16-bit extended+ // Missing the 2 length bytes + mask+ const result = ws.decodeFrame(buf);+ assert.strictEqual(result, null);+ });++ test('rejects unmasked client frame', () => {+ // Server MUST reject unmasked client frames per RFC 6455 Section 5.1+ const buf = Buffer.alloc(7);+ buf[0] = 0x81; // FIN + TEXT+ buf[1] = 5; // length 5, NO mask bit+ Buffer.from('Hello').copy(buf, 2);+ assert.throws(() => ws.decodeFrame(buf), /mask/i, 'Should reject unmasked client frame');+ });++ test('handles multiple frames in a single buffer', () => {+ const frame1 = makeClientFrame(0x01, 'first');+ const frame2 = makeClientFrame(0x01, 'second');+ const combined = Buffer.concat([frame1, frame2]);++ const result1 = ws.decodeFrame(combined);+ assert(result1, 'Should decode first frame');+ assert.strictEqual(result1.payload.toString(), 'first');+ assert.strictEqual(result1.bytesConsumed, frame1.length);++ const result2 = ws.decodeFrame(combined.slice(result1.bytesConsumed));+ assert(result2, 'Should decode second frame');+ assert.strictEqual(result2.payload.toString(), 'second');+ });++ test('correctly unmasks with all mask byte values', () => {+ // Use a known mask to verify unmasking arithmetic+ const payload = Buffer.from('ABCDEFGH');+ const mask = Buffer.from([0xFF, 0x00, 0xAA, 0x55]);+ const masked = Buffer.alloc(payload.length);+ for (let i = 0; i < payload.length; i++) {+ masked[i] = payload[i] ^ mask[i % 4];+ }++ // Build frame manually+ const header = Buffer.alloc(6);+ header[0] = 0x81; // FIN + TEXT+ header[1] = 0x80 | payload.length;+ mask.copy(header, 2);+ const frame = Buffer.concat([header, masked]);++ const result = ws.decodeFrame(frame);+ assert.strictEqual(result.payload.toString(), 'ABCDEFGH');+ });++ // ========== Frame Encoding Boundary at 65535/65536 ==========+ console.log('\n--- Frame Size Boundaries ---');++ test('encodes frame at exactly 65535 bytes (max 16-bit)', () => {+ const payload = Buffer.alloc(65535, 0x45);+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);+ assert.strictEqual(frame[1], 126);+ assert.strictEqual(frame.readUInt16BE(2), 65535);+ assert.strictEqual(frame.length, 4 + 65535);+ });++ test('encodes frame at exactly 65536 bytes (min 64-bit)', () => {+ const payload = Buffer.alloc(65536, 0x46);+ const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);+ assert.strictEqual(frame[1], 127);+ assert.strictEqual(Number(frame.readBigUInt64BE(2)), 65536);+ assert.strictEqual(frame.length, 10 + 65536);+ });++ test('decodes frame at 65535 bytes boundary', () => {+ const payload = 'X'.repeat(65535);+ const frame = makeClientFrame(0x01, payload);+ const result = ws.decodeFrame(frame);+ assert(result);+ assert.strictEqual(result.payload.length, 65535);+ });++ test('decodes frame at 65536 bytes boundary', () => {+ const payload = 'Y'.repeat(65536);+ const frame = makeClientFrame(0x01, payload);+ const result = ws.decodeFrame(frame);+ assert(result);+ assert.strictEqual(result.payload.length, 65536);+ });++ // ========== Close Frame with Status Code ==========+ console.log('\n--- Close Frame Details ---');++ test('decodes close frame with status code', () => {+ // Close frame payload: 2-byte status code + optional reason+ const statusBuf = Buffer.alloc(2);+ statusBuf.writeUInt16BE(1000); // Normal closure+ const frame = makeClientFrame(0x08, statusBuf);+ const result = ws.decodeFrame(frame);+ assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);+ assert.strictEqual(result.payload.readUInt16BE(0), 1000);+ });++ test('decodes close frame with status code and reason', () => {+ const reason = 'Normal shutdown';+ const payload = Buffer.alloc(2 + reason.length);+ payload.writeUInt16BE(1000);+ payload.write(reason, 2);+ const frame = makeClientFrame(0x08, payload);+ const result = ws.decodeFrame(frame);+ assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);+ assert.strictEqual(result.payload.slice(2).toString(), reason);+ });++ // ========== JSON Roundtrip ==========+ console.log('\n--- JSON Message Roundtrip ---');++ test('roundtrip encode/decode of JSON message', () => {+ const msg = { type: 'reload' };+ const payload = Buffer.from(JSON.stringify(msg));+ const serverFrame = ws.encodeFrame(ws.OPCODES.TEXT, payload);++ // Verify we can read what we encoded (unmasked server frame)+ // Server frames don't go through decodeFrame (that expects masked),+ // so just verify the payload bytes directly+ let offset;+ if (serverFrame[1] < 126) {+ offset = 2;+ } else if (serverFrame[1] === 126) {+ offset = 4;+ } else {+ offset = 10;+ }+ const decoded = JSON.parse(serverFrame.slice(offset).toString());+ assert.deepStrictEqual(decoded, msg);+ });++ test('roundtrip masked client JSON message', () => {+ const msg = { type: 'click', choice: 'a', text: 'Option A', timestamp: 1706000101 };+ const frame = makeClientFrame(0x01, JSON.stringify(msg));+ const result = ws.decodeFrame(frame);+ const decoded = JSON.parse(result.payload.toString());+ assert.deepStrictEqual(decoded, msg);+ });++ // ========== Summary ==========+ console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);+ if (failed > 0) process.exit(1);+}++runTests();