brain-dev 0.1.0

package/bin/lib/commands/storm.cjs

@@ -0,0 +1,590 @@
+'use strict';
+
+const http = require('node:http');
+const crypto = require('node:crypto');
+const net = require('node:net');
+const fs = require('node:fs');
+const path = require('node:path');
+const { exec } = require('node:child_process');
+const { output, error, success } = require('../core.cjs');
+const { readState, writeState } = require('../state.cjs');
+
+// RFC 6455 WebSocket magic string
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-5AB4085B9ABC';
+
+/**
+ * Compute the Sec-WebSocket-Accept value per RFC 6455.
+ * @param {string} wsKey - Client's Sec-WebSocket-Key
+ * @returns {string} Base64-encoded SHA-1 hash
+ */
+function computeAcceptKey(wsKey) {
+  return crypto.createHash('sha1').update(wsKey + WS_MAGIC).digest('base64');
+}
+
+/**
+ * Parse a WebSocket frame from a buffer per RFC 6455 Section 5.2.
+ * Handles all three payload length modes (<=125, 126=2-byte, 127=8-byte).
+ * Client-to-server frames MUST be masked.
+ * @param {Buffer} buffer
+ * @returns {{ fin: boolean, opcode: number, payload: Buffer, totalLength: number }|null}
+ */
+function parseFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const firstByte = buffer[0];
+  const secondByte = buffer[1];
+
+  const fin = !!(firstByte & 0x80);
+  const opcode = firstByte & 0x0F;
+  const masked = !!(secondByte & 0x80);
+  let payloadLength = secondByte & 0x7F;
+  let offset = 2;
+
+  if (payloadLength === 126) {
+    if (buffer.length < 4) return null;
+    payloadLength = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLength === 127) {
+    if (buffer.length < 10) return null;
+    // Read as BigUInt64BE, convert to number (safe for practical payload sizes)
+    const high = buffer.readUInt32BE(2);
+    const low = buffer.readUInt32BE(6);
+    payloadLength = high * 0x100000000 + low;
+    offset = 10;
+  }
+
+  const maskSize = masked ? 4 : 0;
+  const totalLength = offset + maskSize + payloadLength;
+  if (buffer.length < totalLength) return null;
+
+  let payload;
+  if (masked) {
+    const maskKey = buffer.slice(offset, offset + 4);
+    payload = Buffer.alloc(payloadLength);
+    for (let i = 0; i < payloadLength; i++) {
+      payload[i] = buffer[offset + 4 + i] ^ maskKey[i % 4];
+    }
+  } else {
+    payload = buffer.slice(offset, offset + payloadLength);
+  }
+
+  return { fin, opcode, payload, totalLength };
+}
+
+/**
+ * Build a WebSocket frame for server-to-client transmission.
+ * Server frames MUST NOT be masked per RFC 6455.
+ * Handles all three payload length modes.
+ * @param {string|Buffer} data - Data to send
+ * @param {number} opcode - Frame opcode (default 0x01 for text)
+ * @returns {Buffer}
+ */
+function buildFrame(data, opcode = 0x01) {
+  const payload = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+  const len = payload.length;
+
+  let header;
+  if (len <= 125) {
+    header = Buffer.alloc(2);
+    header[0] = 0x80 | opcode; // FIN + opcode
+    header[1] = len;
+  } else if (len <= 0xFFFF) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | opcode;
+    header[1] = 127;
+    // Write as two 32-bit values for 64-bit length
+    header.writeUInt32BE(Math.floor(len / 0x100000000), 2);
+    header.writeUInt32BE(len % 0x100000000, 6);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+/**
+ * Find an available port by attempting to bind.
+ * Handles EADDRINUSE by trying the next port. No pre-check race condition.
+ * @param {number} startPort
+ * @param {number} maxAttempts
+ * @returns {Promise<number>}
+ */
+function findAvailablePort(startPort, maxAttempts = 10) {
+  return new Promise((resolve, reject) => {
+    let attempt = 0;
+
+    function tryPort(port) {
+      if (attempt >= maxAttempts) {
+        reject(new Error(`No available port found after ${maxAttempts} attempts starting from ${startPort}`));
+        return;
+      }
+      attempt++;
+
+      const tester = net.createServer();
+      tester.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          tryPort(port + 1);
+        } else {
+          reject(err);
+        }
+      });
+      tester.once('listening', () => {
+        tester.close(() => resolve(port));
+      });
+      tester.listen(port);
+    }
+
+    tryPort(startPort);
+  });
+}
+
+/**
+ * Slugify a topic string for use as directory name.
+ * @param {string} topic
+ * @returns {string}
+ */
+function slugify(topic) {
+  return topic
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ * @param {string} dirPath
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Start the brainstorm WebSocket server.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {string} topic - Brainstorm topic
+ * @param {number} port - Port to listen on
+ * @param {boolean} autoOpen - Whether to open browser automatically
+ * @returns {Promise<http.Server>}
+ */
+function startServer(brainDir, topic, port, autoOpen) {
+  return new Promise((resolve, reject) => {
+    const slug = slugify(topic);
+    const sessionDir = path.join(brainDir, 'storm', slug);
+    ensureDir(sessionDir);
+
+    const fragmentsPath = path.join(sessionDir, 'fragments.md');
+    const eventsPath = path.join(sessionDir, 'events.jsonl');
+    const portFilePath = path.join(sessionDir, 'port');
+
+    // Initialize fragments file if it doesn't exist
+    if (!fs.existsSync(fragmentsPath)) {
+      fs.writeFileSync(fragmentsPath, `# Storm: ${topic}\n\n`, 'utf8');
+    }
+
+    const clients = [];
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'storm.html');
+
+    const server = http.createServer((req, res) => {
+      if (req.method === 'GET' && (req.url === '/' || req.url === '')) {
+        // Serve storm HTML template
+        let html;
+        try {
+          html = fs.readFileSync(templatePath, 'utf8');
+        } catch (e) {
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          res.end('Error: storm.html template not found');
+          return;
+        }
+        // Escape HTML entities to prevent XSS
+        const safeTopic = topic
+          .replace(/&/g, '&amp;')
+          .replace(/</g, '&lt;')
+          .replace(/>/g, '&gt;')
+          .replace(/"/g, '&quot;')
+          .replace(/'/g, '&#039;');
+        html = html.replace(/\{\{topic\}\}/g, safeTopic);
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(html);
+      } else if (req.method === 'POST' && req.url === '/shutdown') {
+        // Graceful shutdown endpoint
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('Shutting down...');
+        cleanup();
+      } else {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not found');
+      }
+    });
+
+    // Handle WebSocket upgrade
+    server.on('upgrade', (req, socket) => {
+      const wsKey = req.headers['sec-websocket-key'];
+      if (!wsKey) {
+        socket.destroy();
+        return;
+      }
+
+      const acceptKey = computeAcceptKey(wsKey);
+      const headers = [
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${acceptKey}`,
+        '',
+        ''
+      ].join('\r\n');
+
+      socket.write(headers);
+      clients.push(socket);
+
+      // Send existing fragments on connect
+      if (fs.existsSync(fragmentsPath)) {
+        const content = fs.readFileSync(fragmentsPath, 'utf8');
+        const fragments = parseFragments(content);
+        if (fragments.length > 0) {
+          const syncMsg = JSON.stringify({ type: 'fragments-sync', fragments });
+          socket.write(buildFrame(syncMsg));
+        }
+      }
+
+      let frameBuffer = Buffer.alloc(0);
+
+      socket.on('data', (data) => {
+        frameBuffer = Buffer.concat([frameBuffer, data]);
+
+        while (frameBuffer.length > 0) {
+          const frame = parseFrame(frameBuffer);
+          if (!frame) break;
+
+          frameBuffer = frameBuffer.slice(frame.totalLength);
+
+          // Handle opcodes
+          if (frame.opcode === 0x08) {
+            // Close frame - send close back
+            socket.write(buildFrame(Buffer.alloc(0), 0x08));
+            socket.end();
+            return;
+          }
+
+          if (frame.opcode === 0x09) {
+            // Ping - respond with pong
+            socket.write(buildFrame(frame.payload, 0x0A));
+            continue;
+          }
+
+          if (frame.opcode === 0x0A) {
+            // Pong - ignore
+            continue;
+          }
+
+          if (frame.opcode === 0x01) {
+            // Text frame
+            handleMessage(frame.payload.toString('utf8'), socket);
+          }
+        }
+      });
+
+      socket.on('close', () => {
+        const idx = clients.indexOf(socket);
+        if (idx !== -1) clients.splice(idx, 1);
+      });
+
+      socket.on('error', () => {
+        const idx = clients.indexOf(socket);
+        if (idx !== -1) clients.splice(idx, 1);
+      });
+    });
+
+    /**
+     * Parse fragments from fragments.md content.
+     * Each fragment is a ## section.
+     */
+    function parseFragments(content) {
+      const fragments = [];
+      const sections = content.split(/^## /m).slice(1);
+      for (const section of sections) {
+        const lines = section.split('\n');
+        const id = lines[0].trim().replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+        const body = lines.slice(1).join('\n').trim();
+        fragments.push({ id, title: lines[0].trim(), body });
+      }
+      return fragments;
+    }
+
+    /**
+     * Handle an incoming WebSocket text message.
+     */
+    function handleMessage(text, sender) {
+      let msg;
+      try {
+        msg = JSON.parse(text);
+      } catch {
+        return; // Ignore non-JSON messages
+      }
+
+      if (msg.type === 'add-fragment') {
+        const fragmentId = `f-${Date.now()}`;
+        const title = msg.title || 'Untitled';
+        const body = msg.body || '';
+
+        // Append to fragments.md
+        const entry = `## ${title}\n\n${body}\n\n`;
+        fs.appendFileSync(fragmentsPath, entry, 'utf8');
+
+        // Broadcast to all clients
+        const broadcastMsg = JSON.stringify({
+          type: 'fragment',
+          id: fragmentId,
+          title,
+          body
+        });
+        const frame = buildFrame(broadcastMsg);
+        for (const client of clients) {
+          try { client.write(frame); } catch { /* client disconnected */ }
+        }
+      } else if (msg.type === 'click' || msg.type === 'group' || msg.type === 'drag') {
+        // Persist event to events.jsonl
+        const event = {
+          ...msg,
+          timestamp: msg.timestamp || Date.now(),
+          recorded: new Date().toISOString()
+        };
+        fs.appendFileSync(eventsPath, JSON.stringify(event) + '\n', 'utf8');
+      }
+    }
+
+    /**
+     * Clean shutdown: send close frames, close server, remove port file.
+     */
+    function cleanup() {
+      // Send close frames to all connected clients
+      const closeFrame = buildFrame(Buffer.alloc(0), 0x08);
+      for (const client of clients) {
+        try { client.write(closeFrame); client.end(); } catch { /* ignore */ }
+      }
+      clients.length = 0;
+
+      // Remove port file
+      try { fs.unlinkSync(portFilePath); } catch { /* ignore */ }
+
+      server.close();
+    }
+
+    // Register signal handlers for clean shutdown
+    const sigHandler = () => {
+      success('Shutting down storm server...');
+      cleanup();
+      process.exit(0);
+    };
+    process.on('SIGINT', sigHandler);
+    process.on('SIGTERM', sigHandler);
+
+    server.on('error', (err) => {
+      reject(err);
+    });
+
+    server.listen(port, () => {
+      // Write port file
+      fs.writeFileSync(portFilePath, String(port), 'utf8');
+
+      if (autoOpen) {
+        // macOS: open browser
+        exec(`open http://localhost:${port}`, () => { /* ignore errors */ });
+      }
+
+      resolve(server);
+    });
+  });
+}
+
+/**
+ * Stop a running storm server for a given topic.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {string} topic - Brainstorm topic
+ */
+function stopServer(brainDir, topic) {
+  const slug = slugify(topic);
+  const sessionDir = path.join(brainDir, 'storm', slug);
+  const portFilePath = path.join(sessionDir, 'port');
+
+  if (!fs.existsSync(portFilePath)) {
+    error(`No running storm server found for topic: ${topic}`);
+    return;
+  }
+
+  const port = parseInt(fs.readFileSync(portFilePath, 'utf8').trim(), 10);
+
+  // Send shutdown request to the server
+  const req = http.request({ hostname: 'localhost', port, path: '/shutdown', method: 'POST' }, (res) => {
+    success(`Storm server for "${topic}" stopped (port ${port}).`);
+    // Clean up port file
+    try { fs.unlinkSync(portFilePath); } catch { /* ignore */ }
+  });
+
+  req.on('error', () => {
+    // Server might already be down, just clean up port file
+    try { fs.unlinkSync(portFilePath); } catch { /* ignore */ }
+    success(`Storm server port file cleaned up for "${topic}".`);
+  });
+
+  req.end();
+}
+
+/**
+ * Generate output.md from fragments for a topic.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {string} topic - Brainstorm topic
+ */
+function finalizeSession(brainDir, topic) {
+  const slug = slugify(topic);
+  const sessionDir = path.join(brainDir, 'storm', slug);
+  const fragmentsPath = path.join(sessionDir, 'fragments.md');
+  const outputPath = path.join(sessionDir, 'output.md');
+
+  if (!fs.existsSync(fragmentsPath)) {
+    error(`No fragments found for topic: ${topic}`);
+    return;
+  }
+
+  const fragments = fs.readFileSync(fragmentsPath, 'utf8');
+  const now = new Date().toISOString();
+
+  const outputContent = [
+    `# Storm Output: ${topic}`,
+    '',
+    `**Generated:** ${now}`,
+    `**Session:** ${slug}`,
+    '',
+    '## Fragments',
+    '',
+    fragments,
+    '',
+    '---',
+    '',
+    '*Generated by brain-dev storm --finalize*'
+  ].join('\n');
+
+  fs.writeFileSync(outputPath, outputContent, 'utf8');
+  success(`Output written to .brain/storm/${slug}/output.md`);
+  output({ path: outputPath, topic, fragments: fragments.split('## ').length - 1 },
+    `Finalized ${fragments.split('## ').length - 1} fragments for "${topic}".`);
+}
+
+/**
+ * Parse command-line flags from args array.
+ * @param {string[]} args
+ * @returns {{ flags: object, positional: string[] }}
+ */
+function parseArgs(args) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--stop') {
+      flags.stop = true;
+    } else if (args[i] === '--finalize') {
+      flags.finalize = true;
+    } else if (args[i] === '--port' && i + 1 < args.length) {
+      flags.port = parseInt(args[i + 1], 10);
+      i++;
+    } else if (!args[i].startsWith('--')) {
+      positional.push(args[i]);
+    }
+  }
+
+  return { flags, positional };
+}
+
+/**
+ * Main command handler for brain-dev storm.
+ * @param {string[]} args - CLI arguments
+ */
+async function run(args = []) {
+  const { flags, positional } = parseArgs(args);
+  const brainDir = path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain project found. Run 'brain-dev init' first.");
+    return;
+  }
+
+  const topic = positional.join(' ');
+
+  if (!topic) {
+    error('Usage: brain-dev storm <topic> [--stop] [--port <n>] [--finalize]');
+    return;
+  }
+
+  // Handle --stop subcommand
+  if (flags.stop) {
+    stopServer(brainDir, topic);
+    return;
+  }
+
+  // Handle --finalize subcommand
+  if (flags.finalize) {
+    finalizeSession(brainDir, topic);
+    return;
+  }
+
+  // Default: start server
+  const stormConfig = state.storm || { port: 3456, auto_open: true };
+  const defaultPort = stormConfig.port || 3456;
+  const autoOpen = stormConfig.auto_open !== false;
+
+  let confirmedPort;
+
+  if (flags.port) {
+    // User provided explicit --port, use directly
+    confirmedPort = flags.port;
+  } else {
+    // Find available port starting from default
+    try {
+      const availablePort = await findAvailablePort(defaultPort);
+
+      if (availablePort !== defaultPort) {
+        // Port was busy, inform user
+        output(
+          { defaultPort, availablePort, action: 'port_confirmation' },
+          `[brain] Port ${defaultPort} is busy. Found available port: ${availablePort}. Use this port? (Y/n, or enter custom port)`
+        );
+        // In non-interactive/agent context, use the found port automatically
+        confirmedPort = availablePort;
+      } else {
+        confirmedPort = availablePort;
+      }
+    } catch (e) {
+      error(`Could not find available port: ${e.message}`);
+      return;
+    }
+  }
+
+  // Persist confirmed port to brain.json
+  state.storm = state.storm || {};
+  state.storm.port = confirmedPort;
+  writeState(brainDir, state);
+
+  // Create session directory
+  const slug = slugify(topic);
+  const sessionDir = path.join(brainDir, 'storm', slug);
+  ensureDir(sessionDir);
+
+  try {
+    const server = await startServer(brainDir, topic, confirmedPort, autoOpen);
+    success(`Storm server started at http://localhost:${confirmedPort}`);
+    output(
+      { url: `http://localhost:${confirmedPort}`, topic, slug, port: confirmedPort },
+      `[brain] Storm: "${topic}" - Open http://localhost:${confirmedPort} in your browser\n[brain] Press Ctrl+C to stop the server`
+    );
+  } catch (e) {
+    error(`Failed to start storm server: ${e.message}`);
+  }
+}
+
+module.exports = { run };