Source from repo
Brainstorming Ideas Into Designs

Turn ideas into validated designs and specs through collaborative dialogue before any code is written
obraGitHub obraSource repo Original GitHub link Publisher page
Files
Skill
n/a
Size
50.8 KB
Entrypoint
SKILL.md
Format
git-repo
Open file
scripts/server.cjs

Syntax-highlighted preview of this file as included in the skill package.
Rendered Source
code355 linesFree
scripts/server.cjs
1const crypto = require('crypto');
2const http = require('http');
3const fs = require('fs');
4const path = require('path');
5 
6// ========== WebSocket Protocol (RFC 6455) ==========
7 
8const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
9const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
10 
11function computeAcceptKey(clientKey) {
12  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
13}
14 
15function encodeFrame(opcode, payload) {
16  const fin = 0x80;
17  const len = payload.length;
18  let header;
19 
20  if (len < 126) {
21    header = Buffer.alloc(2);
22    header[0] = fin | opcode;
23    header[1] = len;
24  } else if (len < 65536) {
25    header = Buffer.alloc(4);
26    header[0] = fin | opcode;
27    header[1] = 126;
28    header.writeUInt16BE(len, 2);
29  } else {
30    header = Buffer.alloc(10);
31    header[0] = fin | opcode;
32    header[1] = 127;
33    header.writeBigUInt64BE(BigInt(len), 2);
34  }
35 
36  return Buffer.concat([header, payload]);
37}
38 
39function decodeFrame(buffer) {
40  if (buffer.length < 2) return null;
41 
42  const secondByte = buffer[1];
43  const opcode = buffer[0] & 0x0F;
44  const masked = (secondByte & 0x80) !== 0;
45  let payloadLen = secondByte & 0x7F;
46  let offset = 2;
47 
48  if (!masked) throw new Error('Client frames must be masked');
49 
50  if (payloadLen === 126) {
51    if (buffer.length < 4) return null;
52    payloadLen = buffer.readUInt16BE(2);
53    offset = 4;
54  } else if (payloadLen === 127) {
55    if (buffer.length < 10) return null;
56    payloadLen = Number(buffer.readBigUInt64BE(2));
57    offset = 10;
58  }
59 
60  const maskOffset = offset;
61  const dataOffset = offset + 4;
62  const totalLen = dataOffset + payloadLen;
63  if (buffer.length < totalLen) return null;
64 
65  const mask = buffer.slice(maskOffset, dataOffset);
66  const data = Buffer.alloc(payloadLen);
67  for (let i = 0; i < payloadLen; i++) {
68    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
69  }
70 
71  return { opcode, payload: data, bytesConsumed: totalLen };
72}
73 
74// ========== Configuration ==========
75 
76const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
77const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
78const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
79const SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
80const CONTENT_DIR = path.join(SESSION_DIR, 'content');
81const STATE_DIR = path.join(SESSION_DIR, 'state');
82let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
83 
84const MIME_TYPES = {
85  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
86  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
87  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
88};
89 
90// ========== Templates and Constants ==========
91 
92const WAITING_PAGE = `<!DOCTYPE html>
93<html>
94<head><meta charset="utf-8"><title>Brainstorm Companion</title>
95<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
96h1 { color: #333; } p { color: #666; }</style>
97</head>
98<body><h1>Brainstorm Companion</h1>
99<p>Waiting for the agent to push a screen...</p></body></html>`;
100 
101const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
102const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
103const helperInjection = '<script>\n' + helperScript + '\n</script>';
104 
105// ========== Helper Functions ==========
106 
107function isFullDocument(html) {
108  const trimmed = html.trimStart().toLowerCase();
109  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
110}
111 
112function wrapInFrame(content) {
113  return frameTemplate.replace('<!-- CONTENT -->', content);
114}
115 
116function getNewestScreen() {
117  const files = fs.readdirSync(CONTENT_DIR)
118    .filter(f => f.endsWith('.html'))
119    .map(f => {
120      const fp = path.join(CONTENT_DIR, f);
121      return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
122    })
123    .sort((a, b) => b.mtime - a.mtime);
124  return files.length > 0 ? files[0].path : null;
125}
126 
127// ========== HTTP Request Handler ==========
128 
129function handleRequest(req, res) {
130  touchActivity();
131  if (req.method === 'GET' && req.url === '/') {
132    const screenFile = getNewestScreen();
133    let html = screenFile
134      ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
135      : WAITING_PAGE;
136 
137    if (html.includes('</body>')) {
138      html = html.replace('</body>', helperInjection + '\n</body>');
139    } else {
140      html += helperInjection;
141    }
142 
143    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
144    res.end(html);
145  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
146    const fileName = req.url.slice(7);
147    const filePath = path.join(CONTENT_DIR, path.basename(fileName));
148    if (!fs.existsSync(filePath)) {
149      res.writeHead(404);
150      res.end('Not found');
151      return;
152    }
153    const ext = path.extname(filePath).toLowerCase();
154    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
155    res.writeHead(200, { 'Content-Type': contentType });
156    res.end(fs.readFileSync(filePath));
157  } else {
158    res.writeHead(404);
159    res.end('Not found');
160  }
161}
162 
163// ========== WebSocket Connection Handling ==========
164 
165const clients = new Set();
166 
167function handleUpgrade(req, socket) {
168  const key = req.headers['sec-websocket-key'];
169  if (!key) { socket.destroy(); return; }
170 
171  const accept = computeAcceptKey(key);
172  socket.write(
173    'HTTP/1.1 101 Switching Protocols\r\n' +
174    'Upgrade: websocket\r\n' +
175    'Connection: Upgrade\r\n' +
176    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
177  );
178 
179  let buffer = Buffer.alloc(0);
180  clients.add(socket);
181 
182  socket.on('data', (chunk) => {
183    buffer = Buffer.concat([buffer, chunk]);
184    while (buffer.length > 0) {
185      let result;
186      try {
187        result = decodeFrame(buffer);
188      } catch (e) {
189        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
190        clients.delete(socket);
191        return;
192      }
193      if (!result) break;
194      buffer = buffer.slice(result.bytesConsumed);
195 
196      switch (result.opcode) {
197        case OPCODES.TEXT:
198          handleMessage(result.payload.toString());
199          break;
200        case OPCODES.CLOSE:
201          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
202          clients.delete(socket);
203          return;
204        case OPCODES.PING:
205          socket.write(encodeFrame(OPCODES.PONG, result.payload));
206          break;
207        case OPCODES.PONG:
208          break;
209        default: {
210          const closeBuf = Buffer.alloc(2);
211          closeBuf.writeUInt16BE(1003);
212          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
213          clients.delete(socket);
214          return;
215        }
216      }
217    }
218  });
219 
220  socket.on('close', () => clients.delete(socket));
221  socket.on('error', () => clients.delete(socket));
222}
223 
224function handleMessage(text) {
225  let event;
226  try {
227    event = JSON.parse(text);
228  } catch (e) {
229    console.error('Failed to parse WebSocket message:', e.message);
230    return;
231  }
232  touchActivity();
233  console.log(JSON.stringify({ source: 'user-event', ...event }));
234  if (event.choice) {
235    const eventsFile = path.join(STATE_DIR, 'events');
236    fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
237  }
238}
239 
240function broadcast(msg) {
241  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
242  for (const socket of clients) {
243    try { socket.write(frame); } catch (e) { clients.delete(socket); }
244  }
245}
246 
247// ========== Activity Tracking ==========
248 
249const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
250let lastActivity = Date.now();
251 
252function touchActivity() {
253  lastActivity = Date.now();
254}
255 
256// ========== File Watching ==========
257 
258const debounceTimers = new Map();
259 
260// ========== Server Startup ==========
261 
262function startServer() {
263  if (!fs.existsSync(CONTENT_DIR)) fs.mkdirSync(CONTENT_DIR, { recursive: true });
264  if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
265 
266  // Track known files to distinguish new screens from updates.
267  // macOS fs.watch reports 'rename' for both new files and overwrites,
268  // so we can't rely on eventType alone.
269  const knownFiles = new Set(
270    fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.html'))
271  );
272 
273  const server = http.createServer(handleRequest);
274  server.on('upgrade', handleUpgrade);
275 
276  const watcher = fs.watch(CONTENT_DIR, (eventType, filename) => {
277    if (!filename || !filename.endsWith('.html')) return;
278 
279    if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
280    debounceTimers.set(filename, setTimeout(() => {
281      debounceTimers.delete(filename);
282      const filePath = path.join(CONTENT_DIR, filename);
283 
284      if (!fs.existsSync(filePath)) return; // file was deleted
285      touchActivity();
286 
287      if (!knownFiles.has(filename)) {
288        knownFiles.add(filename);
289        const eventsFile = path.join(STATE_DIR, 'events');
290        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
291        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
292      } else {
293        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
294      }
295 
296      broadcast({ type: 'reload' });
297    }, 100));
298  });
299  watcher.on('error', (err) => console.error('fs.watch error:', err.message));
300 
301  function shutdown(reason) {
302    console.log(JSON.stringify({ type: 'server-stopped', reason }));
303    const infoFile = path.join(STATE_DIR, 'server-info');
304    if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
305    fs.writeFileSync(
306      path.join(STATE_DIR, 'server-stopped'),
307      JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
308    );
309    watcher.close();
310    clearInterval(lifecycleCheck);
311    server.close(() => process.exit(0));
312  }
313 
314  function ownerAlive() {
315    if (!ownerPid) return true;
316    try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
317  }
318 
319  // Check every 60s: exit if owner process died or idle for 30 minutes
320  const lifecycleCheck = setInterval(() => {
321    if (!ownerAlive()) shutdown('owner process exited');
322    else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
323  }, 60 * 1000);
324  lifecycleCheck.unref();
325 
326  // Validate owner PID at startup. If it's already dead, the PID resolution
327  // was wrong (common on WSL, Tailscale SSH, and cross-user scenarios).
328  // Disable monitoring and rely on the idle timeout instead.
329  if (ownerPid) {
330    try { process.kill(ownerPid, 0); }
331    catch (e) {
332      if (e.code !== 'EPERM') {
333        console.log(JSON.stringify({ type: 'owner-pid-invalid', pid: ownerPid, reason: 'dead at startup' }));
334        ownerPid = null;
335      }
336    }
337  }
338 
339  server.listen(PORT, HOST, () => {
340    const info = JSON.stringify({
341      type: 'server-started', port: Number(PORT), host: HOST,
342      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
343      screen_dir: CONTENT_DIR, state_dir: STATE_DIR
344    });
345    console.log(info);
346    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n');
347  });
348}
349 
350if (require.main === module) {
351  startServer();
352}
353 
354module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
355
Preparing the source view

Brainstorming Ideas Into Designs

scripts/server.cjs
