Setting the file. One moment. function isTruthyEnv
— line 227
This file
- Number
- 1.3
- Position
- 3 of 7
- Type
- JavaScript
- Size
- 25 KB
- Lines
- 723
scripts/server.cjs
JavaScript·723 lines·25 KB
{ TEXT:
0x01
, CLOSE:
0x08
, PING:
0x09
, PONG:
0x0A
};
9const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
10const MAX_FRAME_PAYLOAD_BYTES = 10 * 1024 * 1024;
11
12function computeAcceptKey(clientKey) {
13 return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
14}
15
16function encodeFrame(opcode, payload) {
17 const fin = 0x80;
18 const len = payload.length;
19 let header;
20
21 if (len < 126) {
22 header = Buffer.alloc(2);
23 header[0] = fin | opcode;
24 header[1] = len;
25 } else if (len < 65536) {
26 header = Buffer.alloc(4);
27 header[0] = fin | opcode;
28 header[1] = 126;
29 header.writeUInt16BE(len, 2);
30 } else {
31 header = Buffer.alloc(10);
32 header[0] = fin | opcode;
33 header[1] = 127;
34 header.writeBigUInt64BE(BigInt(len), 2);
35 }
36
37 return Buffer.concat([header, payload]);
38}
39
40function decodeFrame(buffer) {
41 if (buffer.length < 2) return null;
42
43 const secondByte = buffer[1];
44 const opcode = buffer[0] & 0x0F;
45 const masked = (secondByte & 0x80) !== 0;
46 let payloadLen = secondByte & 0x7F;
47 let offset = 2;
48
49 if (!masked) throw new Error('Client frames must be masked');
50
51 if (payloadLen === 126) {
52 if (buffer.length < 4) return null;
53 payloadLen = buffer.readUInt16BE(2);
54 offset = 4;
55 } else if (payloadLen === 127) {
56 if (buffer.length < 10) return null;
57 const extendedLen = buffer.readBigUInt64BE(2);
58 if (extendedLen > BigInt(MAX_FRAME_PAYLOAD_BYTES)) {
59 throw new Error('WebSocket frame payload exceeds maximum allowed size');
60 }
61 payloadLen = Number(extendedLen);
62 offset = 10;
63 }
64
65 if (payloadLen > MAX_FRAME_PAYLOAD_BYTES) {
66 throw new Error('WebSocket frame payload exceeds maximum allowed size');
67 }
68
69 const maskOffset = offset;
70 const dataOffset = offset + 4;
71 const totalLen = dataOffset + payloadLen;
72 if (buffer.length < totalLen) return null;
73
74 const mask = buffer.slice(maskOffset, dataOffset);
75 const data = Buffer.alloc(payloadLen);
76 for (let i = 0; i < payloadLen; i++) {
77 data[i] = buffer[dataOffset + i] ^ mask[i % 4];
78 }
79
80 return { opcode, payload: data, bytesConsumed: totalLen };
81}
82
83// ========== Configuration ==========
84
85const PORT_FILE = process.env.BRAINSTORM_PORT_FILE || null;
86const randomPort = () => 49152 + Math.floor(Math.random() * 16383);
87// Prefer an explicit port, else the port this session last bound (so a restart
88// reuses it and an already-open browser tab reconnects), else a random high port.
89function preferredPort() {
90 if (process.env.BRAINSTORM_PORT) return Number(process.env.BRAINSTORM_PORT);
91 if (PORT_FILE) {
92 try {
93 const p = Number(fs.readFileSync(PORT_FILE, 'utf-8').trim());
94 if (Number.isInteger(p) && p > 1023 && p < 65536) return p;
95 } catch (e) { /* no prior port recorded */ }
96 }
97 return randomPort();
98}
99let PORT = preferredPort();
100const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
101const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
102const SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
103const CONTENT_DIR = path.join(SESSION_DIR, 'content');
104const STATE_DIR = path.join(SESSION_DIR, 'state');
105const SUPERPOWERS_VERSION = readSuperpowersVersion();
106const SUPERPOWERS_BRAND_IMAGE_URL = 'https://primeradiant.com/brand/superpowers-visual-brainstorming-logo.png';
107const TELEMETRY_DISABLE_ENV_VARS = [
108 'SUPERPOWERS_DISABLE_TELEMETRY',
109 'DISABLE_TELEMETRY',
110 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC'
111];
112const SUPERPOWERS_TELEMETRY_DISABLED = TELEMETRY_DISABLE_ENV_VARS.some(name => isTruthyEnv(process.env[name]));
113let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
114
115// Per-session secret key. The companion is reachable by any local browser tab
116// and, when bound to a non-loopback host, by any host that can route to it.
117// The key authenticates the real client uniformly across loopback, tunnel, and
118// remote binds — and defeats DNS rebinding — where a Host/Origin allowlist
119// cannot. It rides the served URL as ?key= and is mirrored into a cookie on
120// first load so same-origin subresources and the WebSocket carry it for free.
121// Persisted alongside the port (BRAINSTORM_TOKEN_FILE) so a restart keeps the
122// same key and an already-open tab's cookie still validates.
123const TOKEN_FILE = process.env.BRAINSTORM_TOKEN_FILE || null;
124function generateToken() {
125 return crypto.randomBytes(32).toString('hex');
126}
127
128function chmodOwnerOnly(file) {
129 try { fs.chmodSync(file, 0o600); } catch (e) { /* best effort */ }
130}
131
132function initialToken() {
133 if (process.env.BRAINSTORM_TOKEN) {
134 return { value: process.env.BRAINSTORM_TOKEN, source: 'env' };
135 }
136 if (TOKEN_FILE) {
137 try {
138 const t = fs.readFileSync(TOKEN_FILE, 'utf-8').trim();
139 if (/^[0-9a-f]{32,}$/i.test(t)) {
140 chmodOwnerOnly(TOKEN_FILE);
141 return { value: t, source: 'file' };
142 }
143 } catch (e) { /* no prior token recorded */ }
144 }
145 return { value: generateToken(), source: 'generated' };
146}
147
148const tokenInfo = initialToken();
149let TOKEN = tokenInfo.value;
150let tokenSource = tokenInfo.source;
151let COOKIE_NAME = 'brainstorm-key-' + PORT; // refined to the actual bound port in onListen
152
153const MIME_TYPES = {
154 '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
155 '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
156 '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
157};
158
159// ========== Templates and Constants ==========
160
161function waitingPage() {
162 return renderBranding(`<!DOCTYPE html>
163<html>
164<head><meta charset="utf-8"><title>Brainstorm Companion</title>
165<style>
166body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
167h1 { color: #333; } p { color: #666; }
168.brand { display: flex; align-items: center; min-width: 0; overflow: hidden; margin-bottom: 1.5rem; color: #666; font-size: 0.9rem; line-height: 1; }
169.brand a { color: inherit; text-decoration: none; display: flex; align-items: center; gap: 0.5rem; min-width: 0; max-width: 100%; line-height: 1; }
170.brand-copy { display: block; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; line-height: 1; transform: translateY(-1px); }
171.brand-logo { display: block; height: 1em; width: auto; max-width: 180px; filter: invert(1); }
172</style>
173</head>
174<body><!-- BRANDING --><h1>Brainstorm Companion</h1>
175<p>Waiting for the agent to push a screen...</p></body></html>`);
176}
177
178const FORBIDDEN_PAGE = `<!DOCTYPE html>
179<html>
180<head><meta charset="utf-8"><title>Session key required</title>
181<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
182h1 { color: #333; } p { color: #666; } code { background: #f0f0f0; padding: 0.1em 0.3em; border-radius: 4px; }</style>
183</head>
184<body><h1>Session key required</h1>
185<p>This page needs the full URL your coding agent gave you, including the
186<code>?key=…</code> part. Copy the complete URL and open it again.</p></body></html>`;
187
188function bootstrapPage(key) {
189 const jsonKey = JSON.stringify(String(key));
190 return `<!DOCTYPE html>
191<html>
192<head><meta charset="utf-8"><title>Opening Brainstorm Companion</title></head>
193<body>
194<script>
195try { sessionStorage.setItem('brainstorm-session-key', ${jsonKey}); } catch (e) {}
196location.replace('/');
197</script>
198</body>
199</html>`;
200}
201
202const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
203const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
204const helperInjection = '<script>\n' + helperScript + '\n</script>';
205
206// ========== Helper Functions ==========
207
208function readSuperpowersVersion() {
209 const root = path.join(__dirname, '../../..');
210 const manifests = [
211 path.join(root, 'package.json'),
212 path.join(root, '.codex-plugin/plugin.json')
213 ];
214
215 for (const manifest of manifests) {
216 try {
217 const data = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
218 if (data.version) return String(data.version);
219 } catch (e) {
220 // Packaged Codex plugins omit package.json; try the next manifest.
221 }
222 }
223
224 return 'unknown';
225}
226
227function isTruthyEnv(value) {
228 if (!value) return false;
229 const normalized = String(value).trim().toLowerCase();
230 if (!normalized) return false;
231 return !['0', 'false', 'no', 'off'].includes(normalized);
232}
233
234function escapeHtmlText(value) {
235 return String(value)
236 .replace(/&/g, '&')
237 .replace(/</g, '<')
238 .replace(/>/g, '>')
239 .replace(/"/g, '"');
240}
241
242function brandMarkup() {
243 const version = escapeHtmlText(SUPERPOWERS_VERSION);
244 const text = SUPERPOWERS_TELEMETRY_DISABLED
245 ? 'Prime Radiant Superpowers v' + version
246 : 'Superpowers v' + version;
247 const logo = SUPERPOWERS_TELEMETRY_DISABLED
248 ? ''
249 : '<img class="brand-logo" src="' + SUPERPOWERS_BRAND_IMAGE_URL + '?v=' + encodeURIComponent(SUPERPOWERS_VERSION) + '" alt="Prime Radiant" referrerpolicy="no-referrer" decoding="async">';
250
251 return '<div class="brand"><a href="https://github.com/obra/superpowers">' + logo + '<span class="brand-copy">' + text + '</span></a></div>';
252}
253
254function renderBranding(html) {
255 return html.split('<!-- BRANDING -->').join(brandMarkup());
256}
257
258function isFullDocument(html) {
259 const trimmed = html.trimStart().toLowerCase();
260 return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
261}
262
263function wrapInFrame(content) {
264 return renderBranding(frameTemplate).replace('<!-- CONTENT -->', content);
265}
266
267function getNewestScreen() {
268 const files = fs.readdirSync(CONTENT_DIR)
269 .filter(f => !f.startsWith('.') && f.endsWith('.html'))
270 .map(f => {
271 const fp = path.join(CONTENT_DIR, f);
272 if (!isRegularFileInsideContentDir(fp)) return null;
273 return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
274 })
275 .filter(Boolean)
276 .sort((a, b) => b.mtime - a.mtime);
277 return files.length > 0 ? files[0].path : null;
278}
279
280function urlHostForHttp(host) {
281 const h = String(host);
282 if (h.startsWith('[') && h.endsWith(']')) return h;
283 return h.includes(':') ? '[' + h + ']' : h;
284}
285
286function companionUrl() {
287 return 'http://' + urlHostForHttp(URL_HOST) + ':' + PORT + '/?key=' + TOKEN;
288}
289
290function browserLauncherForPlatform(url, {
291 platform = process.platform,
292 osRelease = require('os').release(),
293 env = process.env
294} = {}) {
295 const isWSL = platform === 'linux' && /microsoft/i.test(osRelease);
296 if (platform === 'darwin') return { bin: 'open', args: [url] };
297 if (platform === 'win32' || isWSL) {
298 return { bin: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] };
299 }
300 if (env.DISPLAY || env.WAYLAND_DISPLAY) return { bin: 'xdg-open', args: [url] };
301 return null;
302}
303
304function isRegularFileInsideContentDir(filePath) {
305 let stat, realContentDir, realFilePath;
306 try {
307 stat = fs.lstatSync(filePath);
308 if (stat.isSymbolicLink()) return false;
309 if (!stat.isFile()) return false;
310 if (stat.nlink !== 1) return false;
311 realContentDir = fs.realpathSync(CONTENT_DIR);
312 realFilePath = fs.realpathSync(filePath);
313 } catch (e) {
314 return false;
315 }
316 return realFilePath.startsWith(realContentDir + path.sep);
317}
318
319// ========== Authentication ==========
320
321function timingSafeEqualStr(a, b) {
322 const ab = Buffer.from(String(a));
323 const bb = Buffer.from(String(b));
324 if (ab.length !== bb.length) return false;
325 return crypto.timingSafeEqual(ab, bb);
326}
327
328function parseCookies(header) {
329 const out = {};
330 if (!header) return out;
331 for (const part of header.split(';')) {
332 const eq = part.indexOf('=');
333 if (eq < 0) continue;
334 out[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
335 }
336 return out;
337}
338
339// A request is authorized if it carries the session key as ?key= or as the
340// session cookie. Both are compared in constant time.
341function isAuthorized(req) {
342 const q = req.url.indexOf('?');
343 if (q >= 0) {
344 const params = new URLSearchParams(req.url.slice(q + 1));
345 if (params.has('key')) {
346 const key = params.get('key');
347 return Boolean(key && timingSafeEqualStr(key, TOKEN));
348 }
349 }
350 const cookie = parseCookies(req.headers['cookie'])[COOKIE_NAME];
351 if (cookie && timingSafeEqualStr(cookie, TOKEN)) return true;
352 return false;
353}
354
355function pathnameOf(url) {
356 const q = url.indexOf('?');
357 return q >= 0 ? url.slice(0, q) : url;
358}
359
360function queryKey(url) {
361 const q = url.indexOf('?');
362 if (q < 0) return null;
363 return new URLSearchParams(url.slice(q + 1)).get('key');
364}
365
366function securityHeaders(headers = {}) {
367 return {
368 'Referrer-Policy': 'no-referrer',
369 'Cache-Control': 'no-store',
370 'X-Frame-Options': 'DENY',
371 'Content-Security-Policy': "frame-ancestors 'none'",
372 'Cross-Origin-Resource-Policy': 'same-origin',
373 ...headers
374 };
375}
376
377function isAllowedWebSocketOrigin(req) {
378 const origin = req.headers.origin;
379 if (!origin) return true;
380 const host = req.headers.host;
381 if (!host) return false;
382 return origin === 'http://' + host;
383}
384
385// ========== HTTP Request Handler ==========
386
387function handleRequest(req, res) {
388 if (!isAuthorized(req)) {
389 res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
390 res.end(FORBIDDEN_PAGE);
391 return;
392 }
393 touchActivity(); // only authorized requests count as activity
394
395 // Mirror the key into a cookie so same-origin subresources (/files/*) can
396 // authenticate after bootstrap. HttpOnly keeps it away from page scripts; the
397 // WebSocket Origin check below is what blocks cross-origin localhost injection.
398 res.setHeader('Set-Cookie',
399 COOKIE_NAME + '=' + TOKEN + '; HttpOnly; SameSite=Strict; Path=/');
400
401 const pathname = pathnameOf(req.url);
402 const keyFromQuery = queryKey(req.url);
403 if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
404 res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
405 res.end(bootstrapPage(keyFromQuery));
406 } else if (req.method === 'GET' && pathname === '/') {
407 const screenFile = getNewestScreen();
408 let html = screenFile
409 ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
410 : waitingPage();
411
412 if (html.includes('</body>')) {
413 html = html.replace('</body>', helperInjection + '\n</body>');
414 } else {
415 html += helperInjection;
416 }
417
418 res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
419 res.end(html);
420 } else if (req.method === 'GET' && pathname.startsWith('/files/')) {
421 const fileName = path.basename(pathname.slice(7));
422 const filePath = path.join(CONTENT_DIR, fileName);
423 // Reject empty/dotfile names and anything that isn't a regular file —
424 // `/files/` would otherwise resolve to CONTENT_DIR and crash readFileSync (EISDIR).
425 if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) {
426 res.writeHead(404, securityHeaders());
427 res.end('Not found');
428 return;
429 }
430 const ext = path.extname(filePath).toLowerCase();
431 const contentType = MIME_TYPES[ext] || 'application/octet-stream';
432 res.writeHead(200, securityHeaders({ 'Content-Type': contentType }));
433 res.end(fs.readFileSync(filePath));
434 } else {
435 res.writeHead(404, securityHeaders());
436 res.end('Not found');
437 }
438}
439
440// ========== WebSocket Connection Handling ==========
441
442const clients = new Set();
443
444function handleUpgrade(req, socket) {
445 if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; }
446
447 const key = req.headers['sec-websocket-key'];
448 if (!key) { socket.destroy(); return; }
449
450 const accept = computeAcceptKey(key);
451 socket.write(
452 'HTTP/1.1 101 Switching Protocols\r\n' +
453 'Upgrade: websocket\r\n' +
454 'Connection: Upgrade\r\n' +
455 'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
456 );
457
458 let buffer = Buffer.alloc(0);
459 clients.add(socket);
460
461 socket.on('data', (chunk) => {
462 buffer = Buffer.concat([buffer, chunk]);
463 while (buffer.length > 0) {
464 let result;
465 try {
466 result = decodeFrame(buffer);
467 } catch (e) {
468 socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
469 clients.delete(socket);
470 return;
471 }
472 if (!result) break;
473 buffer = buffer.slice(result.bytesConsumed);
474
475 switch (result.opcode) {
476 case OPCODES.TEXT:
477 handleMessage(result.payload.toString());
478 break;
479 case OPCODES.CLOSE:
480 socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
481 clients.delete(socket);
482 return;
483 case OPCODES.PING:
484 socket.write(encodeFrame(OPCODES.PONG, result.payload));
485 break;
486 case OPCODES.PONG:
487 break;
488 default: {
489 const closeBuf = Buffer.alloc(2);
490 closeBuf.writeUInt16BE(1003);
491 socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
492 clients.delete(socket);
493 return;
494 }
495 }
496 }
497 });
498
499 socket.on('close', () => clients.delete(socket));
500 socket.on('error', () => clients.delete(socket));
501}
502
503function handleMessage(text) {
504 let event;
505 try {
506 event = JSON.parse(text);
507 } catch (e) {
508 console.error('Failed to parse WebSocket message:', e.message);
509 return;
510 }
511 touchActivity();
512 console.log(JSON.stringify({ source: 'user-event', ...event }));
513 if (event && event.choice) {
514 const eventsFile = path.join(STATE_DIR, 'events');
515 fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
516 }
517}
518
519function broadcast(msg) {
520 const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
521 for (const socket of clients) {
522 try { socket.write(frame); } catch (e) { clients.delete(socket); }
523 }
524}
525
526// Best-effort: open the user's browser the first time a screen is actually ready
527// to show. Skips when disabled, on a non-loopback (remote) bind, or when a
528// browser is already connected. Override the launcher with BRAINSTORM_OPEN_CMD.
529let browserOpened = false;
530function maybeOpenBrowser() {
531 if (browserOpened) return;
532 browserOpened = true;
533 if (!process.env.BRAINSTORM_OPEN) return; // opt-in: only after the user approves the companion
534 if (HOST !== '127.0.0.1' && HOST !== 'localhost') return;
535 if (clients.size > 0) return; // the user already opened it
536 const url = companionUrl(); // must carry the key or the gate 403s it
537 const cp = require('child_process');
538 // Operator-provided launcher: run as given (this env var is trusted operator input).
539 if (process.env.BRAINSTORM_OPEN_CMD) {
540 try { cp.exec(process.env.BRAINSTORM_OPEN_CMD + ' ' + JSON.stringify(url), () => {}); } catch (e) { /* best effort */ }
541 return;
542 }
543 // Platform launchers: pass the URL as an argv element via execFile (no shell),
544 // so a url-host containing shell metacharacters can't inject a command.
545 const launcher = browserLauncherForPlatform(url);
546 if (!launcher) return; // headless: nothing to open
547 try { cp.execFile(launcher.bin, launcher.args, () => {}); } catch (e) { /* best effort */ }
548}
549
550// ========== Activity Tracking ==========
551
552// Idle timeout: shut down after this long with no activity. Default 4 hours;
553// override with BRAINSTORM_IDLE_TIMEOUT_MS (start-server.sh: --idle-timeout-minutes).
554const IDLE_TIMEOUT_MS = (() => {
555 const ms = Number(process.env.BRAINSTORM_IDLE_TIMEOUT_MS);
556 return Number.isFinite(ms) && ms > 0 ? ms : 4 * 60 * 60 * 1000;
557})();
558// How often the watchdog checks for owner-death / idleness. Configurable mainly
559// so tests can run fast; production default is 60s.
560const LIFECYCLE_CHECK_MS = (() => {
561 const ms = Number(process.env.BRAINSTORM_LIFECYCLE_CHECK_MS);
562 return Number.isFinite(ms) && ms > 0 ? ms : 60 * 1000;
563})();
564let lastActivity = Date.now();
565
566function touchActivity() {
567 lastActivity = Date.now();
568}
569
570// ========== File Watching ==========
571
572const debounceTimers = new Map();
573
574// ========== Server Startup ==========
575
576function startServer() {
577 if (!fs.existsSync(CONTENT_DIR)) fs.mkdirSync(CONTENT_DIR, { recursive: true });
578 if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
579
580 // Track known files to distinguish new screens from updates.
581 // macOS fs.watch reports 'rename' for both new files and overwrites,
582 // so we can't rely on eventType alone.
583 const knownFiles = new Set(
584 fs.readdirSync(CONTENT_DIR).filter(f => !f.startsWith('.') && f.endsWith('.html'))
585 );
586
587 const server = http.createServer(handleRequest);
588 server.on('upgrade', handleUpgrade);
589
590 const watcher = fs.watch(CONTENT_DIR, (eventType, filename) => {
591 if (!filename || filename.startsWith('.') || !filename.endsWith('.html')) return;
592
593 if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
594 debounceTimers.set(filename, setTimeout(() => {
595 debounceTimers.delete(filename);
596 const filePath = path.join(CONTENT_DIR, filename);
597
598 if (!fs.existsSync(filePath)) return; // file was deleted
599 touchActivity();
600
601 if (!knownFiles.has(filename)) {
602 knownFiles.add(filename);
603 const eventsFile = path.join(STATE_DIR, 'events');
604 if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
605 console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
606 maybeOpenBrowser();
607 } else {
608 console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
609 }
610
611 broadcast({ type: 'reload' });
612 }, 100));
613 });
614 watcher.on('error', (err) => console.error('fs.watch error:', err.message));
615
616 function shutdown(reason) {
617 console.log(JSON.stringify({ type: 'server-stopped', reason }));
618 const infoFile = path.join(STATE_DIR, 'server-info');
619 if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
620 fs.writeFileSync(
621 path.join(STATE_DIR, 'server-stopped'),
622 JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
623 );
624 watcher.close();
625 clearInterval(lifecycleCheck);
626 // Close any upgraded WebSocket sockets so server.close() can complete and
627 // the process actually exits instead of lingering on an open connection.
628 for (const socket of clients) {
629 try { socket.destroy(); } catch (e) { /* already gone */ }
630 }
631 server.close(() => process.exit(0));
632 }
633
634 function ownerAlive() {
635 if (!ownerPid) return true;
636 try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
637 }
638
639 // Periodically exit if the owner process died or we've been idle too long.
640 const lifecycleCheck = setInterval(() => {
641 if (!ownerAlive()) shutdown('owner process exited');
642 else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
643 }, LIFECYCLE_CHECK_MS);
644 lifecycleCheck.unref();
645
646 // Validate owner PID at startup. If it's already dead, the PID resolution
647 // was wrong (common on WSL, Tailscale SSH, and cross-user scenarios).
648 // Disable monitoring and rely on the idle timeout instead.
649 if (ownerPid) {
650 try { process.kill(ownerPid, 0); }
651 catch (e) {
652 if (e.code !== 'EPERM') {
653 console.log(JSON.stringify({ type: 'owner-pid-invalid', pid: ownerPid, reason: 'dead at startup' }));
654 ownerPid = null;
655 }
656 }
657 }
658
659 // If the preferred port is already taken (e.g. a previous server is still
660 // alive), fall back to a random port once instead of failing.
661 let triedFallback = false;
662
663 function onListen() {
664 // Cookie name keys on the ACTUAL bound port (may differ from the preferred
665 // one after an EADDRINUSE fallback) so it can't collide with another server's
666 // cookie in the shared localhost jar.
667 COOKIE_NAME = 'brainstorm-key-' + PORT;
668 // Record the bound port AND token so the next restart of this session reuses
669 // them — but ONLY when we got our preferred port. On a fallback we bound a
670 // *different* port because someone else holds the preferred one; persisting
671 // would overwrite the shared files and strand that other session's open tab.
672 if (PORT_FILE && !triedFallback) {
673 try { fs.writeFileSync(PORT_FILE, String(PORT)); } catch (e) { /* best effort */ }
674 if (TOKEN_FILE) {
675 try {
676 fs.writeFileSync(TOKEN_FILE, TOKEN, { mode: 0o600 });
677 chmodOwnerOnly(TOKEN_FILE);
678 } catch (e) { /* best effort */ }
679 }
680 }
681 const info = JSON.stringify({
682 type: 'server-started', port: Number(PORT), host: HOST,
683 url_host: URL_HOST, url: companionUrl(),
684 screen_dir: CONTENT_DIR, state_dir: STATE_DIR, idle_timeout_ms: IDLE_TIMEOUT_MS
685 });
686 console.log(info);
687 // server-info embeds the key — keep it owner-only.
688 fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n', { mode: 0o600 });
689 }
690
691 server.on('error', (err) => {
692 if (err.code === 'EADDRINUSE' && !triedFallback) {
693 if (tokenSource === 'env') {
694 console.error('Server failed to bind: preferred port is in use and BRAINSTORM_TOKEN is set; refusing fallback with explicit token');
695 process.exit(1);
696 }
697 triedFallback = true;
698 PORT = randomPort();
699 if (tokenSource === 'file') {
700 TOKEN = generateToken();
701 tokenSource = 'generated-fallback';
702 }
703 server.listen(PORT, HOST, onListen);
704 } else {
705 console.error('Server failed to bind:', err.message);
706 process.exit(1);
707 }
708 });
709 server.listen(PORT, HOST, onListen);
710}
711
712if (require.main === module) {
713 startServer();
714}
715
716module.exports = {
717 computeAcceptKey,
718 encodeFrame,
719 decodeFrame,
720 browserLauncherForPlatform,
721 OPCODES,
722 MAX_FRAME_PAYLOAD_BYTES
723};