1#!/usr/bin/env node
2/**
3 * Live variant mode server (self-contained, zero dependencies).
4 *
5 * Serves the browser script (/live.js), the detection overlay (/detect.js),
6 * uses Server-Sent Events (SSE) for server→browser push, and HTTP POST for
7 * browser→server events. Agent communicates via HTTP long-poll (/poll).
8 *
9 * Usage:
10 *   node <scripts_path>/live-server.mjs              # start
11 *   node <scripts_path>/live-server.mjs stop         # stop + remove injected live.js tag
12 *   node <scripts_path>/live-server.mjs stop --keep-inject   # stop only
13 *   node <scripts_path>/live-server.mjs --help
14 */
15 
16import http from 'node:http';
17import { randomUUID } from 'node:crypto';
18import { spawn, execFileSync } from 'node:child_process';
19import fs from 'node:fs';
20import path from 'node:path';
21import net from 'node:net';
22import { fileURLToPath } from 'node:url';
23import { parseDesignMd } from './design-parser.mjs';
24import { resolveContextDir } from './load-context.mjs';
25import { createLiveSessionStore } from './live-session-store.mjs';
26import {
27  getDesignSidecarPath,
28  getLiveAnnotationsDir,
29  readLiveServerInfo,
30  removeLiveServerInfo,
31  resolveDesignSidecarPath,
32  writeLiveServerInfo,
33} from './impeccable-paths.mjs';
34 
35const __dirname = path.dirname(fileURLToPath(import.meta.url));
36// PRODUCT.md / DESIGN.md live wherever load-context.mjs resolves. The generated
37// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
38// DESIGN.json fallback for existing projects.
39const CONTEXT_DIR = resolveContextDir(process.cwd());
40const DEFAULT_POLL_TIMEOUT = 600_000;   // 10 min — agent re-polls on timeout anyway
41const SSE_HEARTBEAT_INTERVAL = 30_000;  // keepalive ping every 30s
42 
43// ---------------------------------------------------------------------------
44// Port detection
45// ---------------------------------------------------------------------------
46 
47async function findOpenPort(start = 8400) {
48  return new Promise((resolve) => {
49    const srv = net.createServer();
50    srv.listen(start, '127.0.0.1', () => {
51      const port = srv.address().port;
52      srv.close(() => resolve(port));
53    });
54    srv.on('error', () => resolve(findOpenPort(start + 1)));
55  });
56}
57 
58// ---------------------------------------------------------------------------
59// Session state
60// ---------------------------------------------------------------------------
61 
62const state = {
63  token: null,
64  port: null,
65  sseClients: new Set(),   // SSE response objects (server→browser push)
66  pendingEvents: [],        // browser events waiting for agent ack ({ event, leaseUntil })
67  pendingPolls: [],         // agent poll callbacks waiting for browser events
68  exitTimer: null,
69  sessionDir: null,         // per-session tmp dir for annotation screenshots
70  sessionStore: null,
71  leaseTimer: null,
72};
73 
74// Cap per-annotation upload size. A full 1920×1080 PNG is typically <1 MB;
75// cap at 10 MB to guard against runaway writes from a misbehaving client.
76const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
77 
78function enqueueEvent(event) {
79  if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
80  state.pendingEvents.push({ event, leaseUntil: 0 });
81  flushPendingPolls();
82}
83 
84function restorePendingEventsFromStore() {
85  if (!state.sessionStore) return;
86  for (const snapshot of state.sessionStore.listActiveSessions()) {
87    if (snapshot.pendingEvent) enqueueEvent(snapshot.pendingEvent);
88  }
89}
90 
91function findAvailablePendingEvent(now = Date.now()) {
92  return state.pendingEvents.find((entry) => !entry.leaseUntil || entry.leaseUntil <= now);
93}
94 
95function leaseEvent(entry, leaseMs) {
96  if (!entry.event?.id) {
97    const idx = state.pendingEvents.indexOf(entry);
98    if (idx !== -1) state.pendingEvents.splice(idx, 1);
99    return entry.event;
100  }
101  entry.leaseUntil = Date.now() + leaseMs;
102  return entry.event;
103}
104 
105function acknowledgePendingEvent(id) {
106  if (!id) return false;
107  const idx = state.pendingEvents.findIndex((entry) => entry.event?.id === id);
108  if (idx === -1) return false;
109  state.pendingEvents.splice(idx, 1);
110  scheduleLeaseFlush();
111  return true;
112}
113 
114function scheduleLeaseFlush() {
115  if (state.leaseTimer) {
116    clearTimeout(state.leaseTimer);
117    state.leaseTimer = null;
118  }
119  if (state.pendingPolls.length === 0) return;
120  const now = Date.now();
121  const nextLeaseUntil = state.pendingEvents
122    .map((entry) => entry.leaseUntil || 0)
123    .filter((leaseUntil) => leaseUntil > now)
124    .sort((a, b) => a - b)[0];
125  if (!nextLeaseUntil) return;
126  state.leaseTimer = setTimeout(() => {
127    state.leaseTimer = null;
128    flushPendingPolls();
129  }, Math.max(0, nextLeaseUntil - now));
130}
131 
132function flushPendingPolls() {
133  while (state.pendingPolls.length > 0) {
134    const entry = findAvailablePendingEvent();
135    if (!entry) {
136      scheduleLeaseFlush();
137      return;
138    }
139    const poll = state.pendingPolls.shift();
140    poll.resolve(leaseEvent(entry, poll.leaseMs));
141  }
142  scheduleLeaseFlush();
143}
144 
145/** Push a message to all connected SSE clients. */
146function broadcast(msg) {
147  const data = 'data: ' + JSON.stringify(msg) + '\n\n';
148  for (const res of state.sseClients) {
149    try { res.write(data); } catch { /* client gone */ }
150  }
151}
152 
153// ---------------------------------------------------------------------------
154// Load scripts
155// ---------------------------------------------------------------------------
156 
157function loadBrowserScripts() {
158  // Detection script: look relative to the skill scripts dir, then fall back
159  // to the npm package location (cli/engine/detect-antipatterns-browser.js).
160  // This one IS cached — detect.js rarely changes during a session.
161  const detectPaths = [
162    path.join(__dirname, '..', '..', '..', '..', 'cli', 'engine', 'detect-antipatterns-browser.js'),
163    path.join(process.cwd(), 'node_modules', 'impeccable', 'cli', 'engine', 'detect-antipatterns-browser.js'),
164  ];
165  let detectScript = '';
166  for (const p of detectPaths) {
167    try { detectScript = fs.readFileSync(p, 'utf-8'); break; } catch { /* try next */ }
168  }
169 
170  // live-browser.js: DO NOT cache. Return the path so the /live.js handler
171  // can re-read on every request. Editing the browser script during iteration
172  // should land on the next tab reload, not require a server restart.
173  const sessionPath = path.join(__dirname, 'live-browser-session.js');
174  const livePath = path.join(__dirname, 'live-browser.js');
175  for (const p of [sessionPath, livePath]) {
176    if (!fs.existsSync(p)) {
177      process.stderr.write('Error: live browser script not found at ' + p + '\n');
178      process.exit(1);
179    }
180  }
181 
182  return { detectScript, sessionPath, livePath };
183}
184 
185function hasProjectContext() {
186  // PRODUCT.md carries brand voice / anti-references — that's what determines
187  // whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
188  // concern, surfaced by the design panel's own empty state. Legacy
189  // .impeccable.md is auto-migrated to PRODUCT.md by load-context.mjs.
190  try {
191    fs.accessSync(path.join(CONTEXT_DIR, 'PRODUCT.md'), fs.constants.R_OK);
192    return true;
193  } catch { return false; }
194}
195 
196function statOrNull(filePath) {
197  try { return fs.statSync(filePath); } catch { return null; }
198}
199 
200// ---------------------------------------------------------------------------
201// Validation (inline — no external import needed for self-contained script)
202// ---------------------------------------------------------------------------
203 
204const VISUAL_ACTIONS = [
205  'impeccable', 'bolder', 'quieter', 'distill', 'polish', 'typeset',
206  'colorize', 'layout', 'adapt', 'animate', 'delight', 'overdrive',
207];
208 
209// Browser generates ids via crypto.randomUUID().slice(0, 8) (8 hex chars)
210// and variantIds via String(small integer). Restrict to those shapes so
211// any value that reaches a downstream child_process or DOM selector is
212// inert by construction.
213const ID_PATTERN = /^[0-9a-f]{8}$/;
214const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
215 
216function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
217function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
218 
219function validateEvent(msg) {
220  if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
221  switch (msg.type) {
222    case 'generate':
223      if (!isValidId(msg.id)) return 'generate: missing or malformed id';
224      if (!msg.action || !VISUAL_ACTIONS.includes(msg.action)) return 'generate: invalid action';
225      if (!Number.isInteger(msg.count) || msg.count < 1 || msg.count > 8) return 'generate: count must be 1-8';
226      if (!msg.element || !msg.element.outerHTML) return 'generate: missing element context';
227      // Optional annotation fields (all-or-nothing: if any present, all must be well-formed).
228      if (msg.screenshotPath !== undefined && typeof msg.screenshotPath !== 'string') return 'generate: screenshotPath must be string';
229      if (msg.comments !== undefined && !Array.isArray(msg.comments)) return 'generate: comments must be array';
230      if (msg.strokes !== undefined && !Array.isArray(msg.strokes)) return 'generate: strokes must be array';
231      return null;
232    case 'accept':
233      if (!isValidId(msg.id)) return 'accept: missing or malformed id';
234      if (!isValidVariantId(msg.variantId)) return 'accept: missing or malformed variantId';
235      if (msg.paramValues !== undefined) {
236        if (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues)) {
237          return 'accept: paramValues must be an object';
238        }
239      }
240      return null;
241    case 'discard':
242      return isValidId(msg.id) ? null : 'discard: missing or malformed id';
243    case 'checkpoint':
244      if (!isValidId(msg.id)) return 'checkpoint: missing or malformed id';
245      if (!Number.isInteger(msg.revision) || msg.revision < 0) return 'checkpoint: revision must be a non-negative integer';
246      if (msg.paramValues !== undefined && (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues))) {
247        return 'checkpoint: paramValues must be an object';
248      }
249      return null;
250    case 'exit':
251      return null;
252    case 'prefetch':
253      if (!msg.pageUrl || typeof msg.pageUrl !== 'string') return 'prefetch: missing pageUrl';
254      return null;
255    default:
256      return 'Unknown event type: ' + msg.type;
257  }
258}
259 
260// ---------------------------------------------------------------------------
261// HTTP request handler
262// ---------------------------------------------------------------------------
263 
264function createRequestHandler({ detectScript, sessionPath, livePath }) {
265  return (req, res) => {
266    const url = new URL(req.url, `http://localhost:${state.port}`);
267    res.setHeader('Access-Control-Allow-Origin', '*');
268    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
269    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
270    if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
271 
272    const p = url.pathname;
273 
274    // --- Scripts ---
275    if (p === '/live.js') {
276      // Re-read from disk each request so edits to live-browser.js land on
277      // the next tab reload. No-store headers prevent browser caching across
278      // sessions — during iteration, a cached old script silently breaks
279      // every subsequent session.
280      let sessionScript;
281      let liveScript;
282      try {
283        sessionScript = fs.readFileSync(sessionPath, 'utf-8');
284        liveScript = fs.readFileSync(livePath, 'utf-8');
285      } catch (err) {
286        res.writeHead(500, { 'Content-Type': 'text/plain' });
287        res.end('Error reading live browser scripts: ' + err.message);
288        return;
289      }
290      const body =
291        `window.__IMPECCABLE_TOKEN__ = '${state.token}';\n` +
292        `window.__IMPECCABLE_PORT__ = ${state.port};\n` +
293        sessionScript + '\n' +
294        liveScript;
295      res.writeHead(200, {
296        'Content-Type': 'application/javascript',
297        'Cache-Control': 'no-store, no-cache, must-revalidate, max-age=0',
298        'Pragma': 'no-cache',
299      });
300      res.end(body);
301      return;
302    }
303    if (p === '/detect.js' || p === '/') {
304      if (!detectScript) { res.writeHead(404); res.end('Not available'); return; }
305      res.writeHead(200, { 'Content-Type': 'application/javascript' });
306      res.end(detectScript);
307      return;
308    }
309 
310    // --- Vendored modern-screenshot (UMD build) ---
311    // Lazy-loaded by live.js when the user clicks Go; exposes
312    // window.modernScreenshot.domToBlob(...) for capture.
313    if (p === '/modern-screenshot.js') {
314      const vendorPath = path.join(__dirname, 'modern-screenshot.umd.js');
315      try {
316        res.writeHead(200, {
317          'Content-Type': 'application/javascript',
318          'Cache-Control': 'public, max-age=31536000, immutable',
319        });
320        res.end(fs.readFileSync(vendorPath));
321      } catch {
322        res.writeHead(404); res.end('Vendor script not found');
323      }
324      return;
325    }
326 
327    // --- Annotation upload (browser → server, raw PNG body) ---
328    // Client generates the eventId, POSTs the PNG, then POSTs the generate
329    // event with screenshotPath already set. Keeps bytes out of the SSE/poll
330    // bridge and preserves the "one shot from the user's POV" UX.
331    if (p === '/annotation' && req.method === 'POST') {
332      const token = url.searchParams.get('token');
333      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
334      const eventId = url.searchParams.get('eventId');
335      if (!eventId || !/^[A-Za-z0-9_-]{1,64}$/.test(eventId)) {
336        res.writeHead(400, { 'Content-Type': 'application/json' });
337        res.end(JSON.stringify({ error: 'Invalid eventId' }));
338        return;
339      }
340      if ((req.headers['content-type'] || '').toLowerCase() !== 'image/png') {
341        res.writeHead(415, { 'Content-Type': 'application/json' });
342        res.end(JSON.stringify({ error: 'Content-Type must be image/png' }));
343        return;
344      }
345      if (!state.sessionDir) {
346        res.writeHead(500, { 'Content-Type': 'application/json' });
347        res.end(JSON.stringify({ error: 'Session dir unavailable' }));
348        return;
349      }
350      const chunks = [];
351      let total = 0;
352      let aborted = false;
353      req.on('data', (c) => {
354        if (aborted) return;
355        total += c.length;
356        if (total > MAX_ANNOTATION_BYTES) {
357          aborted = true;
358          res.writeHead(413, { 'Content-Type': 'application/json' });
359          res.end(JSON.stringify({ error: 'Payload too large' }));
360          req.destroy();
361          return;
362        }
363        chunks.push(c);
364      });
365      req.on('end', () => {
366        if (aborted) return;
367        const absPath = path.join(state.sessionDir, eventId + '.png');
368        try {
369          fs.writeFileSync(absPath, Buffer.concat(chunks));
370        } catch (err) {
371          res.writeHead(500, { 'Content-Type': 'application/json' });
372          res.end(JSON.stringify({ error: 'Write failed: ' + err.message }));
373          return;
374        }
375        res.writeHead(200, { 'Content-Type': 'application/json' });
376        res.end(JSON.stringify({ ok: true, path: absPath }));
377      });
378      req.on('error', () => {
379        if (!aborted) {
380          res.writeHead(500, { 'Content-Type': 'application/json' });
381          res.end(JSON.stringify({ error: 'Upload failed' }));
382        }
383      });
384      return;
385    }
386 
387    // --- Health ---
388    if (p === '/status') {
389      const token = url.searchParams.get('token');
390      if (token !== state.token) { res.writeHead(401, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Unauthorized' })); return; }
391      const sessions = state.sessionStore ? state.sessionStore.listActiveSessions() : [];
392      res.writeHead(200, { 'Content-Type': 'application/json' });
393      res.end(JSON.stringify({
394        status: 'ok',
395        port: state.port,
396        connectedClients: state.sseClients.size,
397        pendingEvents: state.pendingEvents.map((entry) => ({
398          id: entry.event?.id,
399          type: entry.event?.type,
400          leased: !!(entry.leaseUntil && entry.leaseUntil > Date.now()),
401          leaseUntil: entry.leaseUntil || null,
402        })),
403        activeSessions: sessions,
404      }));
405      return;
406    }
407 
408    if (p === '/health') {
409      res.writeHead(200, { 'Content-Type': 'application/json' });
410      res.end(JSON.stringify({
411        status: 'ok', port: state.port, mode: 'variant',
412        hasProjectContext: hasProjectContext(),
413        connectedClients: state.sseClients.size,
414      }));
415      return;
416    }
417 
418    // --- Design system (unified v2 response) + raw ---
419    //   /design-system.json    returns both parsed DESIGN.md and .impeccable/design.json
420    //                          sidecar when present. Panel merges them:
421    //                            { present, parsed, sidecar, hasMd, hasSidecar,
422    //                              mdNewerThanJson, parseError?, sidecarError? }
423    //                          - parsed: output of parseDesignMd (frontmatter
424    //                            + six canonical sections) when DESIGN.md exists.
425    //                          - sidecar: .impeccable/design.json contents when present.
426    //                            Expected shape: schemaVersion 2, carrying
427    //                            extensions + components + narrative.
428    //   /design-system/raw     returns DESIGN.md markdown verbatim
429    if (p === '/design-system.json' || p === '/design-system/raw') {
430      const token = url.searchParams.get('token');
431      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
432 
433      const mdPath = path.join(CONTEXT_DIR, 'DESIGN.md');
434      const jsonPath = resolveDesignSidecarPath(process.cwd(), CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
435      const mdStat = statOrNull(mdPath);
436      const jsonStat = statOrNull(jsonPath);
437 
438      if (p === '/design-system/raw') {
439        if (!mdStat) { res.writeHead(404); res.end('Not found'); return; }
440        res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' });
441        res.end(fs.readFileSync(mdPath, 'utf-8'));
442        return;
443      }
444 
445      if (!mdStat && !jsonStat) {
446        res.writeHead(404, { 'Content-Type': 'application/json' });
447        res.end(JSON.stringify({ present: false }));
448        return;
449      }
450 
451      const response = {
452        present: true,
453        hasMd: !!mdStat,
454        hasSidecar: !!jsonStat,
455        mdNewerThanJson: !!(mdStat && jsonStat && mdStat.mtimeMs > jsonStat.mtimeMs + 1000),
456      };
457 
458      if (mdStat) {
459        try {
460          response.parsed = parseDesignMd(fs.readFileSync(mdPath, 'utf-8'));
461        } catch (err) {
462          response.parseError = err.message;
463        }
464      }
465 
466      if (jsonStat) {
467        try {
468          response.sidecar = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
469        } catch (err) {
470          response.sidecarError = 'Failed to parse .impeccable/design.json: ' + err.message;
471        }
472      }
473 
474      res.writeHead(200, { 'Content-Type': 'application/json' });
475      res.end(JSON.stringify(response));
476      return;
477    }
478 
479    // --- Source file (no-HMR fallback) ---
480    if (p === '/source') {
481      const token = url.searchParams.get('token');
482      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
483      const filePath = url.searchParams.get('path');
484      if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
485      const absPath = path.resolve(process.cwd(), filePath);
486      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
487      let content;
488      try { content = fs.readFileSync(absPath, 'utf-8'); }
489      catch { res.writeHead(404); res.end('File not found'); return; }
490      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
491      res.end(content);
492      return;
493    }
494 
495    // --- SSE: server→browser push (replaces WebSocket) ---
496    if (p === '/events' && req.method === 'GET') {
497      const token = url.searchParams.get('token');
498      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
499      res.writeHead(200, {
500        'Content-Type': 'text/event-stream',
501        'Cache-Control': 'no-cache',
502        'Connection': 'keep-alive',
503      });
504      res.write('data: ' + JSON.stringify({
505        type: 'connected',
506        hasProjectContext: hasProjectContext(),
507      }) + '\n\n');
508 
509      state.sseClients.add(res);
510      clearTimeout(state.exitTimer);
511 
512      // Keepalive: SSE comment every 30s prevents silent connection drops.
513      const heartbeat = setInterval(() => {
514        try { res.write(': keepalive\n\n'); } catch { clearInterval(heartbeat); }
515      }, SSE_HEARTBEAT_INTERVAL);
516 
517      req.on('close', () => {
518        clearInterval(heartbeat);
519        state.sseClients.delete(res);
520        if (state.sseClients.size === 0) {
521          clearTimeout(state.exitTimer);
522          state.exitTimer = setTimeout(() => {
523            if (state.sseClients.size === 0) enqueueEvent({ type: 'exit' });
524          }, 8000);
525        }
526      });
527      return;
528    }
529 
530    // --- Browser→server events (replaces WebSocket messages) ---
531    if (p === '/events' && req.method === 'POST') {
532      let body = '';
533      req.on('data', (c) => { body += c; });
534      req.on('end', () => {
535        let msg;
536        try { msg = JSON.parse(body); } catch {
537          res.writeHead(400, { 'Content-Type': 'application/json' });
538          res.end(JSON.stringify({ error: 'Invalid JSON' }));
539          return;
540        }
541        if (msg.token !== state.token) {
542          res.writeHead(401, { 'Content-Type': 'application/json' });
543          res.end(JSON.stringify({ error: 'Unauthorized' }));
544          return;
545        }
546        const error = validateEvent(msg);
547        if (error) {
548          res.writeHead(400, { 'Content-Type': 'application/json' });
549          res.end(JSON.stringify({ error }));
550          return;
551        }
552        if (state.sessionStore && msg.id) {
553          try {
554            state.sessionStore.appendEvent(msg);
555          } catch (err) {
556            res.writeHead(500, { 'Content-Type': 'application/json' });
557            res.end(JSON.stringify({ error: 'session_store_append_failed', message: err.message }));
558            return;
559          }
560        }
561        if (msg.type !== 'checkpoint') enqueueEvent(msg);
562        res.writeHead(200, { 'Content-Type': 'application/json' });
563        res.end(JSON.stringify({ ok: true }));
564      });
565      return;
566    }
567 
568    // --- Stop ---
569    if (p === '/stop') {
570      const token = url.searchParams.get('token');
571      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
572      res.writeHead(200, { 'Content-Type': 'text/plain' });
573      res.end('stopping');
574      shutdown();
575      return;
576    }
577 
578    // --- Agent poll ---
579    if (p === '/poll' && req.method === 'GET') {
580      handlePollGet(req, res, url);
581      return;
582    }
583    if (p === '/poll' && req.method === 'POST') {
584      handlePollPost(req, res);
585      return;
586    }
587 
588    res.writeHead(404); res.end('Not found');
589  };
590}
591 
592// ---------------------------------------------------------------------------
593// Agent poll endpoints (unchanged from WS version)
594// ---------------------------------------------------------------------------
595 
596function handlePollGet(req, res, url) {
597  const token = url.searchParams.get('token');
598  if (token !== state.token) {
599    res.writeHead(401, { 'Content-Type': 'application/json' });
600    res.end(JSON.stringify({ error: 'Unauthorized' }));
601    return;
602  }
603  const timeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
604  const leaseMs = parseInt(url.searchParams.get('leaseMs') || '30000', 10);
605  const available = findAvailablePendingEvent();
606  if (available) {
607    res.writeHead(200, { 'Content-Type': 'application/json' });
608    res.end(JSON.stringify(leaseEvent(available, leaseMs)));
609    return;
610  }
611  const poll = { resolve, leaseMs };
612  const timer = setTimeout(() => {
613    const idx = state.pendingPolls.indexOf(poll);
614    if (idx !== -1) state.pendingPolls.splice(idx, 1);
615    res.writeHead(200, { 'Content-Type': 'application/json' });
616    res.end(JSON.stringify({ type: 'timeout' }));
617  }, timeout);
618  function resolve(event) {
619    clearTimeout(timer);
620    res.writeHead(200, { 'Content-Type': 'application/json' });
621    res.end(JSON.stringify(event));
622  }
623  state.pendingPolls.push(poll);
624  scheduleLeaseFlush();
625  req.on('close', () => {
626    clearTimeout(timer);
627    const idx = state.pendingPolls.indexOf(poll);
628    if (idx !== -1) state.pendingPolls.splice(idx, 1);
629  });
630}
631 
632function handlePollPost(req, res) {
633  let body = '';
634  req.on('data', (c) => { body += c; });
635  req.on('end', () => {
636    let msg;
637    try { msg = JSON.parse(body); } catch {
638      res.writeHead(400, { 'Content-Type': 'application/json' });
639      res.end(JSON.stringify({ error: 'Invalid JSON' }));
640      return;
641    }
642    if (msg.token !== state.token) {
643      res.writeHead(401, { 'Content-Type': 'application/json' });
644      res.end(JSON.stringify({ error: 'Unauthorized' }));
645      return;
646    }
647    acknowledgePendingEvent(msg.id);
648    if (state.sessionStore && msg.id) {
649      try {
650        const eventType = msg.type === 'discard' || msg.type === 'discarded'
651          ? 'discarded'
652          : msg.type === 'complete'
653            ? 'complete'
654            : msg.type === 'error'
655              ? 'agent_error'
656              : 'agent_done';
657        state.sessionStore.appendEvent({
658          type: eventType,
659          id: msg.id,
660          file: msg.file,
661          message: msg.message,
662          carbonize: msg.data?.carbonize === true,
663        });
664      } catch { /* keep reply path best-effort; browser still needs SSE */ }
665    }
666    flushPendingPolls();
667    // Forward the reply to the browser via SSE
668    broadcast({ type: msg.type || 'done', id: msg.id, message: msg.message, file: msg.file, data: msg.data });
669    res.writeHead(200, { 'Content-Type': 'application/json' });
670    res.end(JSON.stringify({ ok: true }));
671  });
672}
673 
674// ---------------------------------------------------------------------------
675// Lifecycle
676// ---------------------------------------------------------------------------
677 
678let httpServer = null;
679 
680function shutdown() {
681  removeLiveServerInfo(process.cwd());
682  if (state.leaseTimer) clearTimeout(state.leaseTimer);
683  state.leaseTimer = null;
684  if (state.sessionDir) {
685    try { fs.rmSync(state.sessionDir, { recursive: true, force: true }); } catch {}
686  }
687  for (const res of state.sseClients) { try { res.end(); } catch {} }
688  state.sseClients.clear();
689  for (const poll of state.pendingPolls) poll.resolve({ type: 'exit' });
690  state.pendingPolls.length = 0;
691  if (httpServer) httpServer.close();
692  process.exit(0);
693}
694 
695// ---------------------------------------------------------------------------
696// Main
697// ---------------------------------------------------------------------------
698 
699const args = process.argv.slice(2);
700 
701if (args.includes('--help') || args.includes('-h')) {
702  console.log(`Usage: node live-server.mjs [options]
703 
704Start the live variant mode server (zero dependencies).
705 
706Commands:
707  (default)     Start the server (foreground)
708  stop          Stop the server and remove the injected live.js script tag
709  stop --keep-inject   Stop the server only (leave the script tag in the HTML entry)
710 
711Options:
712  --background  Start detached, print connection JSON to stdout, then exit
713  --port=PORT   Use a specific port (default: auto-detect starting at 8400)
714  --keep-inject Only with stop: skip live-inject.mjs --remove
715  --help        Show this help
716 
717Endpoints:
718  /live.js             Browser script (element picker + variant cycling)
719  /detect.js           Detection overlay (backwards compatible)
720  /modern-screenshot.js Vendored modern-screenshot UMD build (lazy-loaded by live.js)
721  /annotation          POST raw image/png to stage a variant screenshot
722  /events              SSE stream (server→browser) + POST (browser→server)
723  /poll                Long-poll for agent CLI
724  /source              Raw source file reader (no-HMR fallback)
725  /status              Durable recovery status (token-protected)
726  /health              Health check`);
727  process.exit(0);
728}
729 
730if (args.includes('stop')) {
731  const keepInject = args.includes('--keep-inject');
732  try {
733    const { info } = readLiveServerInfo(process.cwd()) || {};
734    const res = await fetch(`http://localhost:${info.port}/stop?token=${info.token}`);
735    if (res.ok) console.log(`Stopped live server on port ${info.port}.`);
736  } catch {
737    console.log('No running live server found.');
738  }
739  if (!keepInject) {
740    const injectPath = path.join(__dirname, 'live-inject.mjs');
741    try {
742      const out = execFileSync(process.execPath, [injectPath, '--remove'], {
743        encoding: 'utf-8',
744        cwd: process.cwd(),
745      });
746      const line = out.trim().split('\n').filter(Boolean).pop();
747      if (line) {
748        try {
749          const j = JSON.parse(line);
750          if (j.removed === true) {
751            console.log(`Removed live script tag from ${j.file}.`);
752          }
753        } catch {
754          /* ignore non-JSON lines */
755        }
756      }
757    } catch (err) {
758      const detail = err.stderr?.toString?.().trim?.()
759        || err.stdout?.toString?.().trim?.()
760        || err.message
761        || String(err);
762      console.warn(`Note: could not remove live script tag (${detail.split('\n')[0]})`);
763    }
764  }
765  process.exit(0);
766}
767 
768// --background: spawn a detached child server, wait for it to be ready,
769// print the connection JSON, then exit.  This keeps the startup command
770// simple (no shell backgrounding or chained commands).
771if (args.includes('--background')) {
772  const childArgs = args.filter(a => a !== '--background');
773  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...childArgs], {
774    detached: true,
775    stdio: 'ignore',
776    cwd: process.cwd(),
777  });
778  child.unref();
779 
780  // Poll for the PID file (the child writes it once the HTTP server is listening).
781  const deadline = Date.now() + 10_000;
782  while (Date.now() < deadline) {
783    try {
784      const { info } = readLiveServerInfo(process.cwd()) || {};
785      if (info.pid !== process.pid) {
786        // Output JSON so the agent can read port + token from stdout.
787        console.log(JSON.stringify(info));
788        process.exit(0);
789      }
790    } catch { /* not ready yet */ }
791    await new Promise(r => setTimeout(r, 200));
792  }
793  console.error('Timed out waiting for live server to start.');
794  process.exit(1);
795}
796 
797// Check for existing session
798const existingRecord = readLiveServerInfo(process.cwd());
799if (existingRecord?.info) {
800  const existing = existingRecord.info;
801  try {
802    process.kill(existing.pid, 0);
803    console.error(`Live server already running on port ${existing.port} (pid ${existing.pid}).`);
804    console.error('Stop it first with: node ' + path.basename(fileURLToPath(import.meta.url)) + ' stop');
805    process.exit(1);
806  } catch {
807    try { fs.unlinkSync(existingRecord.path); } catch {}
808  }
809}
810 
811state.token = randomUUID();
812state.sessionStore = createLiveSessionStore({ cwd: process.cwd() });
813restorePendingEventsFromStore();
814const portArg = args.find(a => a.startsWith('--port='));
815state.port = portArg ? parseInt(portArg.split('=')[1], 10) : await findOpenPort();
816// Annotation screenshots live in the project root so the agent's Read tool
817// doesn't trip a per-file permission prompt. Sessioned by token so concurrent
818// projects (or quick restarts) don't collide.
819const annotRoot = getLiveAnnotationsDir(process.cwd());
820fs.mkdirSync(annotRoot, { recursive: true });
821state.sessionDir = fs.mkdtempSync(path.join(annotRoot, 'session-'));
822 
823const { detectScript, sessionPath, livePath } = loadBrowserScripts();
824httpServer = http.createServer(createRequestHandler({ detectScript, sessionPath, livePath }));
825 
826httpServer.listen(state.port, '127.0.0.1', () => {
827  writeLiveServerInfo(process.cwd(), { pid: process.pid, port: state.port, token: state.token });
828  const url = `http://localhost:${state.port}`;
829  console.log(`\nImpeccable live server running on ${url}`);
830  console.log(`Token: ${state.token}\n`);
831  console.log(`Inject: <script src="${url}/live.js"><\/script>`);
832  console.log(`Stop:   node ${path.basename(fileURLToPath(import.meta.url))} stop`);
833});
834 
835process.on('SIGINT', shutdown);
836process.on('SIGTERM', shutdown);
837