brainstorm-companion 2.1.2 → 2.1.3

package/README.md

@@ -12,13 +12,13 @@ Zero dependencies. Node.js >= 18 only.
 npm install -g brainstorm-companion
 ```
 
-### Claude Code Setup
+### MCP Setup (Claude Code, Cursor, Windsurf, or any MCP client)
 
 Two parts: the **MCP server** (gives the agent tools) and the **skill** (teaches the agent how to use them well).
 
 #### Step 1: MCP Server
 
-Add to `~/.claude/.mcp.json` (create the file if it doesn't exist):
+**Claude Code:** Add to `~/.claude/.mcp.json` (create the file if it doesn't exist):
 
 ```json
 {
@@ -31,19 +31,11 @@ Add to `~/.claude/.mcp.json` (create the file if it doesn't exist):
 }
 ```
 
-This gives the agent 5 tools: `brainstorm_start_session`, `brainstorm_push_screen`, `brainstorm_read_events`, `brainstorm_clear_screen`, `brainstorm_stop_session`. Full usage docs are embedded in each tool description.
+**Other MCP clients (Cursor, Windsurf, etc.):** Use the same config format your client expects. The MCP server command is `brainstorm-companion --mcp` (stdio JSON-RPC).
 
-**Alternative (no global install):** Use `npx` instead:
-```json
-{
-  "mcpServers": {
-    "brainstorm": {
-      "command": "npx",
-      "args": ["brainstorm-companion@latest", "--mcp"]
-    }
-  }
-}
-```
+This gives the agent 5 tools with full usage docs embedded in each description.
+
+**Alternative (no global install):** Use `npx` instead — replace `"command": "brainstorm-companion"` with `"command": "npx"` and `"args": ["brainstorm-companion@latest", "--mcp"]`.
 
 #### Step 2: Skill (optional but recommended)
 
@@ -66,9 +58,9 @@ mkdir -p .claude/skills
 cp "$(npm root -g)/brainstorm-companion/skill/"*.md .claude/skills/
 ```
 
-#### Step 3: Restart Claude Code
+#### Step 3: Restart your AI coding tool
 
-Restart Claude Code for the MCP server and skill to take effect.
+Restart Claude Code / Cursor / your MCP client for the server and skill to take effect.
 
 ---
 
@@ -360,10 +352,10 @@ Global Options:
 ### `start`
 
 ```
-brainstorm-companion start [--project-dir <path>] [--port <N>] [--host <H>] [--timeout <min>] [--foreground] [--no-open] [--reuse]
+brainstorm-companion start [--project-dir <path>] [--port <N>] [--host <H>] [--timeout <min>] [--no-open] [--reuse]
 ```
 
-Always creates a fresh session with a clean slate. Stops any existing session automatically. Use `--reuse` to keep an existing session and its content. Use `--timeout 30` for auto-cleanup after 30 minutes idle.
+Always creates a fresh session with a clean slate. Server runs in foreground — stays alive as long as the process runs. In Claude Code, use `run_in_background` so the server stays alive while you push content. Use `--reuse` to keep an existing session. Use `--timeout 30` for auto-cleanup.
 
 ### `push`
 
@@ -405,7 +397,7 @@ Shows Session ID, URL, uptime, event count, and active slots.
 
 ## How It Works
 
-1. `start` checks for an existing active session — reuses it if found, otherwise creates a new one with its own port and directory
+1. `start` creates a fresh session with its own port, directory, and server process (foreground — stays alive as long as the process runs)
 2. `push` writes HTML files to the session directory; the file watcher detects changes and broadcasts reload to the browser via WebSocket
 3. The browser auto-reloads and renders content in a themed frame with click capture on `[data-choice]` elements
 4. Click events are sent over WebSocket to the server and appended to a `.events` JSONL file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainstorm-companion",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "AI-assisted visual brainstorming companion",
   "type": "commonjs",
   "license": "MIT",

package/src/cli.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { parseArgs } = require('node:util');
-const { exec, spawn } = require('node:child_process');
+const { exec } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const { SessionManager } = require('./session');
@@ -57,17 +57,20 @@ Key concepts:
 
 Start the brainstorm server and open a browser window.
 
-Always creates a fresh session with a clean slate — no leftover content from
-previous runs. Stops any existing session automatically.
+Always creates a fresh session with a clean slate — no leftover content.
+Stops any existing session automatically. Server runs in foreground (stays
+alive as long as this process runs).
 
-Use --reuse to keep an existing session instead.
+In Claude Code: run with run_in_background so it stays alive while you push content.
+In terminal: run in one tab, push from another. Ctrl+C to stop.
+
+Use --reuse to keep an existing session instead of starting fresh.
 
 Options:
   --project-dir <path>  Session storage location (default: /tmp/brainstorm-companion/)
   --port <number>       Bind to specific port (default: random ephemeral)
   --host <address>      Bind address (default: 127.0.0.1)
   --timeout <minutes>   Auto-stop after N minutes of inactivity (default: none)
-  --foreground          Run server in foreground (don't background)
   --no-open             Don't auto-open browser
   --reuse               Reuse existing session if one is running (keep its content)
 
@@ -206,23 +209,6 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-async function pollForServerInfo(sessionDir, timeoutMs = 5000, intervalMs = 100) {
-  const serverInfoPath = path.join(sessionDir, '.server-info');
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (fs.existsSync(serverInfoPath)) {
-      try {
-        const raw = fs.readFileSync(serverInfoPath, 'utf8');
-        const info = JSON.parse(raw);
-        if (info.url) return info;
-      } catch {
-        // file may be partially written, retry
-      }
-    }
-    await sleep(intervalMs);
-  }
-  return null;
-}
 
 function openBrowser(url) {
   const platform = process.platform;
@@ -265,7 +251,6 @@ async function start(argv) {
       'port':        { type: 'string', default: '0' },
       'host':        { type: 'string', default: '127.0.0.1' },
       'timeout':     { type: 'string' },
-      'foreground':  { type: 'boolean', default: false },
       'no-open':     { type: 'boolean', default: false },
       'reuse':       { type: 'boolean', default: false },
     },
@@ -277,7 +262,6 @@ async function start(argv) {
   const port = parseInt(values['port'], 10) || 0;
   const timeoutMin = values['timeout'] ? parseInt(values['timeout'], 10) : 0;
   const idleTimeoutMs = timeoutMin > 0 ? timeoutMin * 60 * 1000 : 0;
-  const foreground = values['foreground'];
   const noOpen = values['no-open'];
   const reuse = values['reuse'];
 
@@ -310,71 +294,46 @@ async function start(argv) {
 
   const { sessionDir } = session.create();
 
-  if (foreground) {
-    // Run server in-process
-    const { startServer } = require('./server');
-    const instance = startServer({
-      screenDir: sessionDir,
-      host,
-      port,
-      ownerPid: process.pid,
-      idleTimeoutMs,
-    });
-
-    instance.server.once('listening', () => {
-      console.log(`Server started: ${instance.url}`);
-      console.log(`Session ID: ${path.basename(sessionDir)}`);
-      printNextSteps();
-      if (!noOpen) {
-        openBrowser(instance.url);
-      }
-    });
-
-    instance.server.once('error', (err) => {
-      console.error(`Server error: ${err.message}`);
-      process.exit(1);
-    });
-
-    // Keep process alive
-    process.on('SIGINT', () => {
-      instance.shutdown('sigint');
-      process.exit(0);
-    });
-    process.on('SIGTERM', () => {
-      instance.shutdown('sigterm');
-      process.exit(0);
-    });
-  } else {
-    // Background the server
-    const serverScript = path.join(__dirname, 'server.js');
-    const child = spawn(process.execPath, [serverScript], {
-      detached: true,
-      stdio: 'ignore',
-      env: {
-        ...process.env,
-        BRAINSTORM_DIR: sessionDir,
-        BRAINSTORM_HOST: host,
-        BRAINSTORM_PORT: String(port),
-        BRAINSTORM_IDLE_TIMEOUT: String(idleTimeoutMs),
-      },
-    });
-    child.unref();
+  // Run server in-process (foreground) — this is the only reliable mode
+  // across all environments (Claude Code, Codex, Docker, terminals).
+  // The calling process must stay alive (use run_in_background in Claude Code).
+  const { startServer } = require('./server');
+  const instance = startServer({
+    screenDir: sessionDir,
+    host,
+    port,
+    ownerPid: process.pid,
+    idleTimeoutMs,
+  });
 
-    // Poll for .server-info
-    const serverInfo = await pollForServerInfo(sessionDir, 5000, 100);
-    if (!serverInfo) {
-      console.error('Timed out waiting for server to start.');
-      process.exit(1);
-    }
+  instance.server.once('listening', () => {
+    // Write global pointer so push/events/stop find this session
+    SessionManager.writeActivePointer(sessionDir);
 
-    console.log(`Server started: ${serverInfo.url}`);
+    console.log(`Server started: ${instance.url}`);
     console.log(`Session ID: ${path.basename(sessionDir)}`);
     printNextSteps();
-
     if (!noOpen) {
-      openBrowser(serverInfo.url);
+      openBrowser(instance.url);
     }
-  }
+  });
+
+  instance.server.once('error', (err) => {
+    console.error(`Server error: ${err.message}`);
+    process.exit(1);
+  });
+
+  // Clean up on exit
+  const cleanup = (reason) => {
+    SessionManager.clearActivePointer();
+    instance.shutdown(reason);
+    process.exit(0);
+  };
+  process.on('SIGINT', () => cleanup('sigint'));
+  process.on('SIGTERM', () => cleanup('sigterm'));
+  process.on('exit', () => {
+    SessionManager.clearActivePointer();
+  });
 }
 
 // ---------------------------------------------------------------------------

package/src/server.js

@@ -55,6 +55,16 @@ function wrapInFrame(content) {
   return frameTemplate.replace('<!-- CONTENT -->', content);
 }
 
+// Like wrapInFrame but strips the header and indicator bar (for iframes in comparison mode)
+function wrapInEmbed(content) {
+  let html = frameTemplate.replace('<!-- CONTENT -->', content);
+  // Remove header
+  html = html.replace(/<div class="header">[\s\S]*?<\/div>\s*<div class="main">/, '<div class="main">');
+  // Remove indicator bar (the actual HTML element, not the CSS)
+  html = html.replace(/\s*<div class="indicator-bar" id="indicator-bar">[\s\S]*?<\/div>\s*(?=<\/body>)/, '\n');
+  return html;
+}
+
 function getNewestScreen(screenDir) {
   let files;
   try {
@@ -256,7 +266,8 @@ function startServer(config = {}) {
         return;
       }
       const raw = fs.readFileSync(slotFile, 'utf-8');
-      let html = isFullDocument(raw) ? raw : wrapInFrame(raw);
+      // Slots are shown in iframes inside comparison page — skip the header/indicator
+      let html = isFullDocument(raw) ? raw : wrapInEmbed(raw);
       const slotNeeds = detectLibraries(html);
       const slotCdnTags = buildInjections(slotNeeds);
       if (slotCdnTags && html.includes('</head>')) {

package/src/session.js

@@ -4,6 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const DEFAULT_BASE = path.join('/tmp', 'brainstorm-companion');
+const ACTIVE_POINTER = path.join(DEFAULT_BASE, '.active');
 
 class SessionManager {
   constructor(projectDir, targetSessionId) {
@@ -20,32 +21,63 @@ class SessionManager {
     return { sessionId, sessionDir };
   }
 
-  getActive(targetSessionId) {
-    if (!fs.existsSync(this.baseDir)) return null;
+  // Write a global pointer so any command can find the active session
+  // regardless of --project-dir
+  static writeActivePointer(sessionDir) {
+    try {
+      fs.mkdirSync(path.dirname(ACTIVE_POINTER), { recursive: true });
+      fs.writeFileSync(ACTIVE_POINTER, sessionDir, 'utf8');
+    } catch { /* ignore */ }
+  }
 
-    // If a specific session ID is requested, go directly to it
-    if (targetSessionId) {
-      const sessionDir = path.join(this.baseDir, targetSessionId);
+  static clearActivePointer() {
+    try { fs.rmSync(ACTIVE_POINTER); } catch { /* ignore */ }
+  }
+
+  // Read the global pointer — returns { sessionDir, serverInfo } or null
+  static readActivePointer() {
+    try {
+      if (!fs.existsSync(ACTIVE_POINTER)) return null;
+      const sessionDir = fs.readFileSync(ACTIVE_POINTER, 'utf8').trim();
       if (!fs.existsSync(sessionDir)) return null;
-      const serverInfoPath = path.join(sessionDir, '.server-info');
-      if (!fs.existsSync(serverInfoPath)) return null;
-      let serverInfo;
-      try {
-        const raw = fs.readFileSync(serverInfoPath, 'utf8');
-        serverInfo = JSON.parse(raw);
-      } catch {
-        return null;
-      }
+      const infoPath = path.join(sessionDir, '.server-info');
+      if (!fs.existsSync(infoPath)) return null;
+      const serverInfo = JSON.parse(fs.readFileSync(infoPath, 'utf8'));
       const pid = serverInfo.pid || serverInfo.serverPid;
       if (pid) {
-        try { process.kill(pid, 0); } catch { return null; }
+        try { process.kill(pid, 0); } catch { return null; } // dead
       } else {
         return null;
       }
-      return { sessionId: targetSessionId, sessionDir, serverInfo };
+      const sessionId = path.basename(sessionDir);
+      return { sessionId, sessionDir, serverInfo };
+    } catch {
+      return null;
+    }
+  }
+
+  getActive(targetSessionId) {
+    // If a specific session ID is requested, search baseDir and pointer
+    if (targetSessionId) {
+      // Try baseDir first
+      const sessionDir = path.join(this.baseDir, targetSessionId);
+      if (fs.existsSync(sessionDir)) {
+        const result = this._checkSession(targetSessionId, sessionDir);
+        if (result) return result;
+      }
+      // Try global pointer
+      const pointer = SessionManager.readActivePointer();
+      if (pointer && pointer.sessionId === targetSessionId) return pointer;
+      return null;
     }
 
-    // No specific session — find most recent with live PID
+    // Try global pointer first (works regardless of --project-dir)
+    const pointer = SessionManager.readActivePointer();
+    if (pointer) return pointer;
+
+    // Fall back to scanning baseDir
+    if (!fs.existsSync(this.baseDir)) return null;
+
     let entries;
     try {
       entries = fs.readdirSync(this.baseDir, { withFileTypes: true });
@@ -60,43 +92,34 @@ class SessionManager {
       try {
         const stat = fs.statSync(sessionDir);
         sessions.push({ name: entry.name, sessionDir, mtime: stat.mtimeMs });
-      } catch {
-        // skip unreadable dirs
-      }
+      } catch { /* skip */ }
     }
 
-    // Sort most recent first
     sessions.sort((a, b) => b.mtime - a.mtime);
 
     for (const { name: sessionId, sessionDir } of sessions) {
-      const serverInfoPath = path.join(sessionDir, '.server-info');
-      if (!fs.existsSync(serverInfoPath)) continue;
-
-      let serverInfo;
-      try {
-        const raw = fs.readFileSync(serverInfoPath, 'utf8');
-        serverInfo = JSON.parse(raw);
-      } catch {
-        continue;
-      }
-
-      const pid = serverInfo.pid || serverInfo.serverPid;
-      if (pid) {
-        try {
-          process.kill(pid, 0);
-        } catch {
-          continue;
-        }
-      } else {
-        continue;
-      }
-
-      return { sessionId, sessionDir, serverInfo };
+      const result = this._checkSession(sessionId, sessionDir);
+      if (result) return result;
     }
 
     return null;
   }
 
+  _checkSession(sessionId, sessionDir) {
+    const serverInfoPath = path.join(sessionDir, '.server-info');
+    if (!fs.existsSync(serverInfoPath)) return null;
+    let serverInfo;
+    try {
+      serverInfo = JSON.parse(fs.readFileSync(serverInfoPath, 'utf8'));
+    } catch {
+      return null;
+    }
+    const pid = serverInfo.pid || serverInfo.serverPid;
+    if (!pid) return null;
+    try { process.kill(pid, 0); } catch { return null; }
+    return { sessionId, sessionDir, serverInfo };
+  }
+
   pushScreen(html, { slot, filename, label } = {}) {
     const active = this.getActive(this.targetSessionId);
     if (!active) throw new Error('No active session found');