@ozsarman/clarityjs 0.6.0

package/src/dev-server.js

@@ -0,0 +1,362 @@
+/**
+ * Clarity.js Development Server
+ *
+ * Zero-config dev server for .clarity projects. Features:
+ *   - Serves static files from the project directory
+ *   - Watches .clarity files for changes and auto-recompiles
+ *   - Live reload via Server-Sent Events (SSE) — no WebSocket needed
+ *   - Injects a tiny client script that reconnects and reloads on change
+ *   - Serves compiled .clarity files as on-the-fly .js responses
+ *   - Color-coded console output with timestamps
+ *
+ * Usage:
+ *   clarity dev [dir] [--port 3000]
+ *
+ * Author: Claude (Anthropic)
+ */
+
+import http       from 'http';
+import fs         from 'fs';
+import path       from 'path';
+import { compile } from './index.js';
+
+// ─── MIME types ───────────────────────────────────────────────────────────────
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.mjs':  'application/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg':  'image/svg+xml',
+  '.png':  'image/png',
+  '.ico':  'image/x-icon',
+  '.woff2':'font/woff2',
+  '.clarity': 'application/javascript; charset=utf-8', // compiled on the fly
+};
+
+// ─── Dev client script (injected into HTML responses) ────────────────────────
+//
+// True HMR — when a .clarity file changes the server recompiles it and sends the
+// new module code via SSE.  The client imports the new module as a Blob URL and
+// calls any registered accept handlers.  If no handler is registered for that
+// path, it falls back to a full location.reload().
+//
+// Usage in your main.js (optional, for zero-reload HMR):
+//
+//   window.__clarity_hmr?.accept('/my-app/App.clarity', (newModule) => {
+//     unmount(); // unmount old root
+//     mount(newModule.default, document.getElementById('app'));
+//   });
+//
+// Without registering an accept handler the client still hot-reloads the page,
+// which is already faster than a cold browser reload because the server has
+// already recompiled before sending.
+const DEV_CLIENT = `
+<script>
+/* Clarity.js HMR client — auto-injected, remove in production */
+window.__clarity_hmr = window.__clarity_hmr || {
+  _handlers: new Map(),
+  accept(path, fn) { this._handlers.set(path, fn); },
+};
+
+(function() {
+  let retries = 0;
+  function connect() {
+    const es = new EventSource('/__clarity_hmr__');
+
+    // Module-level HMR: server sends compiled code + path
+    es.addEventListener('module-update', async (e) => {
+      try {
+        const { path, code } = JSON.parse(e.data);
+        const blob = new Blob([code], { type: 'application/javascript' });
+        const url  = URL.createObjectURL(blob);
+        const mod  = await import(url);
+        URL.revokeObjectURL(url);
+
+        const handler = window.__clarity_hmr._handlers.get(path);
+        if (handler) {
+          console.log('[Clarity HMR] ♻️  Hot-updating', path);
+          handler(mod);
+        } else {
+          console.log('[Clarity HMR] 🔄 No accept handler for', path, '— reloading');
+          location.reload();
+        }
+      } catch (err) {
+        console.error('[Clarity HMR] Failed to apply update:', err);
+        location.reload();
+      }
+    });
+
+    // Fallback: CSS / HTML changes → full reload
+    es.addEventListener('reload', () => {
+      console.log('[Clarity HMR] 🔄 Asset changed — reloading…');
+      location.reload();
+    });
+
+    es.addEventListener('error', () => {
+      es.close();
+      if (retries++ < 30) setTimeout(connect, 1000);
+    });
+    es.addEventListener('open', () => { retries = 0; });
+  }
+  connect();
+})();
+</script>
+`;
+
+// ─── SSE client registry ──────────────────────────────────────────────────────
+const _sseClients = new Set();
+
+function _broadcast(event, data = '') {
+  const msg = `event: ${event}\ndata: ${data}\n\n`;
+  for (const res of _sseClients) {
+    try { res.write(msg); } catch (_) { _sseClients.delete(res); }
+  }
+}
+
+// ─── Logger ───────────────────────────────────────────────────────────────────
+const C = {
+  reset:  '\x1b[0m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+  red:    '\x1b[31m',
+  gray:   '\x1b[90m',
+  bold:   '\x1b[1m',
+};
+
+function log(color, label, msg) {
+  const ts = new Date().toLocaleTimeString('en', { hour12: false });
+  console.log(`${C.gray}${ts}${C.reset} ${color}${label}${C.reset} ${msg}`);
+}
+
+// ─── File watcher ────────────────────────────────────────────────────────────
+function watchDir(dir) {
+  // Use fs.watch recursively where supported (Node 18+ on Linux/macOS)
+  try {
+    fs.watch(dir, { recursive: true }, (event, filename) => {
+      if (!filename) return;
+      if (filename.endsWith('.clarity')) {
+        _handleClarityChange(path.join(dir, filename), filename, dir);
+      } else if (filename.endsWith('.css') || filename.endsWith('.html')) {
+        log(C.yellow, '◆ changed', filename);
+        _broadcast('reload');
+      }
+    });
+    log(C.cyan, '◆ watching', dir);
+  } catch (_) {
+    // Fallback: poll every 500ms
+    log(C.yellow, '◆ watch', 'recursive watch not available — falling back to polling');
+    const mtimes = new Map();
+    setInterval(() => _scanMtimes(dir, mtimes, dir), 500);
+  }
+}
+
+// Recompile a changed .clarity file and broadcast the new module code via SSE.
+// This lets the HMR client hot-swap just the changed module without a full reload.
+function _handleClarityChange(fullPath, filename, rootDir) {
+  log(C.yellow, '◆ changed', filename);
+  try {
+    const source   = fs.readFileSync(fullPath, 'utf8');
+    const urlPath  = '/' + path.relative(rootDir, fullPath).replace(/\\/g, '/');
+    const { code } = compile(source, {
+      filename:    fullPath,
+      runtimePath: '/clarity-runtime.js',
+      routerPath:  '/clarity-router.js',
+      sourceMap:   true,
+    });
+    _broadcast('module-update', JSON.stringify({ path: urlPath, code }));
+    log(C.green, '♻  HMR', filename);
+  } catch (err) {
+    log(C.red, '✗ error', `${filename} — ${err.message}`);
+    // On compile error, send a reload so the browser shows the error overlay
+    _broadcast('reload');
+  }
+}
+
+function _scanMtimes(dir, mtimes, rootDir) {
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        _scanMtimes(full, mtimes, rootDir);
+      } else if (entry.name.endsWith('.clarity')) {
+        const mtime = fs.statSync(full).mtimeMs;
+        if (mtimes.has(full) && mtimes.get(full) !== mtime) {
+          _handleClarityChange(full, entry.name, rootDir);
+        }
+        mtimes.set(full, mtime);
+      } else if (entry.name.endsWith('.css') || entry.name.endsWith('.html')) {
+        const mtime = fs.statSync(full).mtimeMs;
+        if (mtimes.has(full) && mtimes.get(full) !== mtime) {
+          log(C.yellow, '◆ changed', entry.name);
+          _broadcast('reload');
+        }
+        mtimes.set(full, mtime);
+      }
+    }
+  } catch (_) { /* skip unreadable dirs */ }
+}
+
+// ─── Request handler ──────────────────────────────────────────────────────────
+function _handleRequest(req, res, rootDir) {
+  const url = new URL(req.url, 'http://localhost');
+
+  // SSE endpoint — keep connection open for live reload events
+  if (url.pathname === '/__clarity_hmr__') {
+    res.writeHead(200, {
+      'Content-Type':  'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection':    'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write('event: connected\ndata: ok\n\n');
+    _sseClients.add(res);
+    req.on('close', () => _sseClients.delete(res));
+    return;
+  }
+
+  // Resolve file path
+  let filePath = path.join(rootDir, url.pathname);
+
+  // Directory → try index.html
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.isDirectory()) filePath = path.join(filePath, 'index.html');
+  } catch (_) { /* file doesn't exist — handle below */ }
+
+  const ext = path.extname(filePath).toLowerCase();
+
+  // .clarity files → compile on the fly and serve as JS
+  if (ext === '.clarity') {
+    try {
+      const source = fs.readFileSync(filePath, 'utf8');
+      const { code } = compile(source, {
+        filename:    filePath,
+        runtimePath: '/clarity-runtime.js',
+        routerPath:  '/clarity-router.js',
+        sourceMap:   true,
+      });
+      res.writeHead(200, { 'Content-Type': MIME['.js'] });
+      res.end(code);
+      log(C.green, '✓ compiled', url.pathname);
+    } catch (err) {
+      const errMsg = `// Clarity compile error: ${err.message}\nconsole.error(${JSON.stringify(err.message)});`;
+      res.writeHead(200, { 'Content-Type': MIME['.js'] });
+      res.end(errMsg);
+      log(C.red, '✗ error', `${url.pathname} — ${err.message}`);
+    }
+    return;
+  }
+
+  // Serve runtime and router from the clarity-js package itself
+  if (url.pathname === '/clarity-runtime.js') {
+    _serveFile(res, new URL('../src/runtime.js', import.meta.url).pathname, '.js');
+    return;
+  }
+  if (url.pathname === '/clarity-router.js') {
+    try {
+      const routerPath = new URL('../src/router.js', import.meta.url).pathname;
+      let content = fs.readFileSync(routerPath, 'utf8');
+      // Rewrite the relative runtime import so it resolves correctly in the browser.
+      // src/router.js says: import { signal, effect } from './runtime.js'
+      // In the browser context that would resolve to /runtime.js (404).
+      // We rewrite it to the absolute dev-server path instead.
+      content = content.replace(/from ['"]\.\/runtime\.js['"]/g, "from '/clarity-runtime.js'");
+      res.writeHead(200, { 'Content-Type': MIME['.js'] });
+      res.end(content);
+    } catch (err) {
+      res.writeHead(500);
+      res.end(`// could not read router: ${err.message}`);
+    }
+    return;
+  }
+
+  // Regular static file
+  try {
+    let content = fs.readFileSync(filePath);
+
+    // Inject dev client into HTML files
+    if (ext === '.html') {
+      content = content.toString('utf8').replace('</body>', `${DEV_CLIENT}\n</body>`);
+    }
+
+    res.writeHead(200, { 'Content-Type': MIME[ext] ?? 'application/octet-stream' });
+    res.end(content);
+    log(C.gray, '→', url.pathname);
+  } catch (_) {
+    // 404
+    res.writeHead(404, { 'Content-Type': 'text/html' });
+    res.end(`<!DOCTYPE html><html><body>
+      <h1>404 — Not Found</h1>
+      <p><code>${url.pathname}</code> does not exist in <code>${rootDir}</code></p>
+      <p><a href="/">← Back</a></p>
+    </body></html>`);
+    log(C.yellow, '404', url.pathname);
+  }
+}
+
+function _serveFile(res, filePath, ext) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    res.writeHead(200, { 'Content-Type': MIME[ext] ?? 'application/javascript' });
+    res.end(content);
+  } catch (err) {
+    res.writeHead(500);
+    res.end(`// could not read file: ${err.message}`);
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Start the Clarity dev server.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.dir    — directory to serve (default: cwd)
+ * @param {number}  opts.port   — port (default: 3000)
+ * @param {boolean} opts.open   — open browser on start
+ */
+export function startDevServer({ dir = process.cwd(), port = 3000, open = false } = {}) {
+  const rootDir = path.resolve(dir);
+
+  const server = http.createServer((req, res) => {
+    _handleRequest(req, res, rootDir);
+  });
+
+  server.listen(port, () => {
+    console.log('');
+    console.log(`  ${C.bold}${C.cyan}Clarity.js Dev Server${C.reset}`);
+    console.log(`  ${C.green}➜${C.reset}  Local:    ${C.cyan}http://localhost:${port}${C.reset}`);
+    console.log(`  ${C.green}➜${C.reset}  Root:     ${C.gray}${rootDir}${C.reset}`);
+    console.log(`  ${C.green}➜${C.reset}  Press ${C.bold}Ctrl+C${C.reset} to stop`);
+    console.log('');
+
+    watchDir(rootDir);
+
+    if (open) {
+      // Try to open browser cross-platform
+      const opener = process.platform === 'darwin' ? 'open'
+                   : process.platform === 'win32'  ? 'start'
+                   : 'xdg-open';
+      import('child_process').then(({ exec }) => exec(`${opener} http://localhost:${port}`));
+    }
+  });
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`${C.red}✗ Port ${port} is already in use.${C.reset} Try --port ${port + 1}`);
+    } else {
+      console.error(`${C.red}✗ Server error:${C.reset}`, err.message);
+    }
+    process.exit(1);
+  });
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log(`\n${C.yellow}◆ Shutting down…${C.reset}`);
+    server.close(() => process.exit(0));
+  });
+
+  return server;
+}