zero-query 0.4.9 → 0.6.3

package/cli/commands/dev/overlay.js

@@ -0,0 +1,317 @@
+/**
+ * cli/commands/dev/overlay.js — Client-side error overlay + SSE live-reload
+ *
+ * Returns an HTML <script> snippet that is injected before </body> in
+ * every HTML response served by the dev server.  Responsibilities:
+ *
+ *   1. Error Overlay — full-screen dark overlay with code frames, stack
+ *      traces, and ZQueryError metadata.  Dismissable via Esc or ×.
+ *   2. Runtime error hooks — window.onerror, unhandledrejection, AND
+ *      the zQuery $.onError() hook so framework-level errors are
+ *      surfaced in the overlay automatically.
+ *   3. SSE connection — listens for reload / css / error:syntax /
+ *      error:clear events from the dev server watcher.
+ */
+
+'use strict';
+
+// The snippet is a self-contained IIFE — no external dependencies.
+// It must work in all browsers that support EventSource (IE11 excluded).
+
+const OVERLAY_SCRIPT = `<script>
+(function(){
+  // =====================================================================
+  // Error overlay
+  // =====================================================================
+  var overlayEl = null;
+
+  var OVERLAY_CSS =
+    'position:fixed;top:0;left:0;width:100%;height:100%;' +
+    'background:rgba(0,0,0,0.92);color:#fff;z-index:2147483647;' +
+    'font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;' +
+    'font-size:13px;overflow-y:auto;padding:0;margin:0;box-sizing:border-box;';
+
+  var HEADER_CSS =
+    'padding:20px 24px 12px;border-bottom:1px solid rgba(255,255,255,0.1);' +
+    'display:flex;align-items:flex-start;justify-content:space-between;';
+
+  var BADGE_CSS =
+    'display:inline-block;padding:3px 8px;border-radius:4px;font-size:11px;' +
+    'font-weight:700;text-transform:uppercase;letter-spacing:0.5px;margin-bottom:8px;';
+
+  // Map ZQueryError code prefixes to colours so devs can see at a glance
+  // which subsystem produced the error.
+  var CODE_COLORS = {
+    'ZQ_REACTIVE':  '#9b59b6',
+    'ZQ_SIGNAL':    '#9b59b6',
+    'ZQ_EFFECT':    '#9b59b6',
+    'ZQ_EXPR':      '#2980b9',
+    'ZQ_COMP':      '#16a085',
+    'ZQ_ROUTER':    '#d35400',
+    'ZQ_STORE':     '#8e44ad',
+    'ZQ_HTTP':      '#2c3e50',
+    'ZQ_DEV':       '#e74c3c',
+    'ZQ_INVALID':   '#7f8c8d',
+  };
+
+  function badgeColor(data) {
+    if (data.code) {
+      var keys = Object.keys(CODE_COLORS);
+      for (var i = 0; i < keys.length; i++) {
+        if (data.code.indexOf(keys[i]) === 0) return CODE_COLORS[keys[i]];
+      }
+    }
+    if (data.type && /syntax|parse/i.test(data.type)) return '#e74c3c';
+    return '#e67e22';
+  }
+
+  function esc(s) {
+    var d = document.createElement('div');
+    d.appendChild(document.createTextNode(s));
+    return d.innerHTML;
+  }
+
+  function createOverlay(data) {
+    removeOverlay();
+    var wrap = document.createElement('div');
+    wrap.id = '__zq_error_overlay';
+    wrap.setAttribute('style', OVERLAY_CSS);
+    wrap.setAttribute('tabindex', '-1');
+
+    var color = badgeColor(data);
+    var html = '';
+
+    // ----- header row -----
+    html += '<div style="' + HEADER_CSS + '">';
+    html += '<div>';
+
+    // Error code badge (if present)
+    if (data.code) {
+      html += '<span style="' + BADGE_CSS + 'background:' + color + ';margin-right:6px;">' + esc(data.code) + '</span>';
+    }
+    // Type badge
+    html += '<span style="' + BADGE_CSS + 'background:' + (data.code ? 'rgba(255,255,255,0.1)' : color) + ';">' + esc(data.type || 'Error') + '</span>';
+
+    // Message
+    html += '<div style="font-size:18px;font-weight:600;line-height:1.4;color:#ff6b6b;margin-top:4px;">';
+    html += esc(data.message || 'Unknown error');
+    html += '</div></div>';
+
+    // Close button
+    html += '<button id="__zq_close" style="' +
+      'background:none;border:1px solid rgba(255,255,255,0.2);color:#999;' +
+      'font-size:20px;cursor:pointer;border-radius:6px;width:32px;height:32px;' +
+      'display:flex;align-items:center;justify-content:center;flex-shrink:0;' +
+      'margin-left:16px;transition:all 0.15s;"' +
+      ' onmouseover="this.style.color=\\'#fff\\';this.style.borderColor=\\'rgba(255,255,255,0.5)\\'"' +
+      ' onmouseout="this.style.color=\\'#999\\';this.style.borderColor=\\'rgba(255,255,255,0.2)\\'"' +
+      '>&times;</button>';
+    html += '</div>';
+
+    // ----- file location -----
+    if (data.file) {
+      html += '<div style="padding:10px 24px;color:#8be9fd;font-size:13px;">';
+      html += '<span style="color:#888;">File: </span>' + esc(data.file);
+      if (data.line) html += '<span style="color:#888;">:</span>' + data.line;
+      if (data.column) html += '<span style="color:#888;">:</span>' + data.column;
+      html += '</div>';
+    }
+
+    // ----- ZQueryError context (key/value pairs) -----
+    if (data.context && typeof data.context === 'object' && Object.keys(data.context).length) {
+      html += '<div style="padding:8px 24px;display:flex;flex-wrap:wrap;gap:8px;">';
+      var ctxKeys = Object.keys(data.context);
+      for (var ci = 0; ci < ctxKeys.length; ci++) {
+        var k = ctxKeys[ci], v = data.context[k];
+        html += '<span style="background:rgba(255,255,255,0.06);border:1px solid rgba(255,255,255,0.08);' +
+          'padding:3px 10px;border-radius:4px;font-size:12px;">' +
+          '<span style="color:#888;">' + esc(k) + ': </span>' +
+          '<span style="color:#f1fa8c;">' + esc(typeof v === 'object' ? JSON.stringify(v) : String(v)) + '</span>' +
+          '</span>';
+      }
+      html += '</div>';
+    }
+
+    // ----- code frame -----
+    if (data.frame) {
+      html += '<pre style="' +
+        'margin:0;padding:16px 24px;background:rgba(255,255,255,0.04);' +
+        'border-top:1px solid rgba(255,255,255,0.06);' +
+        'border-bottom:1px solid rgba(255,255,255,0.06);' +
+        'overflow-x:auto;line-height:1.6;font-size:13px;">';
+      var lines = data.frame.split('\\n');
+      for (var fi = 0; fi < lines.length; fi++) {
+        var fl = lines[fi];
+        if (fl.charAt(0) === '>') {
+          html += '<span style="color:#ff6b6b;font-weight:600;">' + esc(fl) + '</span>\\n';
+        } else if (fl.indexOf('^') !== -1 && fl.trim().replace(/[\\s|^]/g, '') === '') {
+          html += '<span style="color:#e74c3c;font-weight:700;">' + esc(fl) + '</span>\\n';
+        } else {
+          html += '<span style="color:#999;">' + esc(fl) + '</span>\\n';
+        }
+      }
+      html += '</pre>';
+    }
+
+    // ----- stack trace -----
+    if (data.stack) {
+      html += '<div style="padding:16px 24px;">';
+      html += '<div style="color:#888;font-size:11px;text-transform:uppercase;letter-spacing:0.5px;margin-bottom:8px;">Stack Trace</div>';
+      html += '<pre style="margin:0;color:#bbb;font-size:12px;line-height:1.7;white-space:pre-wrap;word-break:break-word;">';
+      html += esc(data.stack);
+      html += '</pre></div>';
+    }
+
+    // ----- tip -----
+    html += '<div style="padding:16px 24px;color:#555;font-size:11px;border-top:1px solid rgba(255,255,255,0.06);">';
+    html += 'Fix the error and save \\u2014 the overlay will clear automatically. Press <kbd style="' +
+      'background:rgba(255,255,255,0.1);padding:1px 6px;border-radius:3px;font-size:11px;' +
+      '">Esc</kbd> to dismiss.';
+    html += '</div>';
+
+    wrap.innerHTML = html;
+    document.body.appendChild(wrap);
+    overlayEl = wrap;
+
+    var closeBtn = document.getElementById('__zq_close');
+    if (closeBtn) closeBtn.addEventListener('click', removeOverlay);
+    wrap.addEventListener('keydown', function(e) { if (e.key === 'Escape') removeOverlay(); });
+    wrap.focus();
+  }
+
+  function removeOverlay() {
+    if (overlayEl && overlayEl.parentNode) overlayEl.parentNode.removeChild(overlayEl);
+    overlayEl = null;
+  }
+
+  // =====================================================================
+  // Console helper
+  // =====================================================================
+  function logToConsole(data) {
+    var label = data.code ? data.code + ' ' : '';
+    var msg = '\\n%c zQuery DevError %c ' + label + data.type + ': ' + data.message;
+    if (data.file) msg += '\\n  at ' + data.file + (data.line ? ':' + data.line : '') + (data.column ? ':' + data.column : '');
+    console.error(msg, 'background:#e74c3c;color:#fff;padding:2px 6px;border-radius:3px;font-weight:700;', 'color:inherit;');
+    if (data.frame) console.error(data.frame);
+  }
+
+  function cleanStack(stack) {
+    return stack.split('\\n')
+      .filter(function(l) { return l.indexOf('__zq_') === -1 && l.indexOf('EventSource') === -1; })
+      .map(function(l) { return l.replace(location.origin, ''); })
+      .join('\\n');
+  }
+
+  // =====================================================================
+  // Runtime error hooks
+  // =====================================================================
+  window.addEventListener('error', function(e) {
+    if (!e.filename) return;
+    var err = e.error || {};
+    var data = {
+      code:    err.code || '',
+      type:    (err.constructor && err.constructor.name) || 'Error',
+      message: e.message || String(err),
+      file:    e.filename.replace(location.origin, ''),
+      line:    e.lineno || 0,
+      column:  e.colno || 0,
+      context: err.context || null,
+      stack:   err.stack ? cleanStack(err.stack) : ''
+    };
+    createOverlay(data);
+    logToConsole(data);
+  });
+
+  window.addEventListener('unhandledrejection', function(e) {
+    var err = e.reason || {};
+    var data = {
+      code:    err.code || '',
+      type:    err.name === 'ZQueryError' ? 'ZQueryError' : 'Unhandled Promise Rejection',
+      message: err.message || String(err),
+      context: err.context || null,
+      stack:   err.stack ? cleanStack(err.stack) : ''
+    };
+    createOverlay(data);
+    logToConsole(data);
+  });
+
+  // =====================================================================
+  // Hook into zQuery's $.onError() when the library is loaded
+  // =====================================================================
+  function hookZQueryErrors() {
+    // $.onError is set by the framework — wait for it
+    if (typeof $ !== 'undefined' && typeof $.onError === 'function') {
+      $.onError(function(zqErr) {
+        var data = {
+          code:    zqErr.code || '',
+          type:    'ZQueryError',
+          message: zqErr.message,
+          context: zqErr.context || null,
+          stack:   zqErr.stack ? cleanStack(zqErr.stack) : ''
+        };
+        createOverlay(data);
+        logToConsole(data);
+      });
+      return;
+    }
+    // Retry until the library has loaded (max ~5s)
+    if (hookZQueryErrors._tries < 50) {
+      hookZQueryErrors._tries++;
+      setTimeout(hookZQueryErrors, 100);
+    }
+  }
+  hookZQueryErrors._tries = 0;
+  // Defer so the page's own scripts load first
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', hookZQueryErrors);
+  } else {
+    setTimeout(hookZQueryErrors, 0);
+  }
+
+  // =====================================================================
+  // SSE connection (live-reload + server-pushed errors)
+  // =====================================================================
+  var es, reconnectTimer;
+
+  function connect() {
+    es = new EventSource('/__zq_reload');
+
+    es.addEventListener('reload', function() {
+      removeOverlay();
+      location.reload();
+    });
+
+    es.addEventListener('css', function() {
+      var sheets = document.querySelectorAll('link[rel="stylesheet"]');
+      sheets.forEach(function(l) {
+        var href = l.getAttribute('href');
+        if (!href) return;
+        var sep = href.indexOf('?') >= 0 ? '&' : '?';
+        l.setAttribute('href', href.replace(/[?&]_zqr=\\\\d+/, '') + sep + '_zqr=' + Date.now());
+      });
+    });
+
+    es.addEventListener('error:syntax', function(e) {
+      try { var data = JSON.parse(e.data); createOverlay(data); logToConsole(data); } catch(_){}
+    });
+
+    es.addEventListener('error:runtime', function(e) {
+      try { var data = JSON.parse(e.data); createOverlay(data); logToConsole(data); } catch(_){}
+    });
+
+    es.addEventListener('error:clear', function() {
+      removeOverlay();
+    });
+
+    es.onerror = function() {
+      es.close();
+      clearTimeout(reconnectTimer);
+      reconnectTimer = setTimeout(connect, 2000);
+    };
+  }
+
+  connect();
+})();
+</script>`;
+
+module.exports = OVERLAY_SCRIPT;

package/cli/commands/dev/server.js

@@ -0,0 +1,129 @@
+/**
+ * cli/commands/dev/server.js — HTTP server & SSE broadcasting
+ *
+ * Creates the zero-http app, serves static files, injects the
+ * error-overlay snippet into HTML responses, and manages the
+ * SSE connection pool for live-reload events.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const OVERLAY_SCRIPT = require('./overlay');
+
+// ---------------------------------------------------------------------------
+// SSE client pool
+// ---------------------------------------------------------------------------
+
+class SSEPool {
+  constructor() {
+    this._clients = new Set();
+  }
+
+  add(sse) {
+    this._clients.add(sse);
+    sse.on('close', () => this._clients.delete(sse));
+  }
+
+  broadcast(eventType, data) {
+    for (const sse of this._clients) {
+      try { sse.event(eventType, data || ''); } catch { this._clients.delete(sse); }
+    }
+  }
+
+  closeAll() {
+    for (const sse of this._clients) {
+      try { sse.close(); } catch { /* ignore */ }
+    }
+    this._clients.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} opts
+ * @param {string} opts.root        — absolute path to project root
+ * @param {string} opts.htmlEntry   — e.g. 'index.html'
+ * @param {number} opts.port
+ * @param {boolean} opts.noIntercept — skip zquery.min.js auto-resolve
+ * @returns {{ app, pool: SSEPool, listen: Function }}
+ */
+function createServer({ root, htmlEntry, port, noIntercept }) {
+  let zeroHttp;
+  try {
+    zeroHttp = require('zero-http');
+  } catch {
+    console.error(`\n  \u2717 zero-http is required for the dev server.`);
+    console.error(`    Install it: npm install zero-http --save-dev\n`);
+    process.exit(1);
+  }
+
+  const { createApp, static: serveStatic } = zeroHttp;
+
+  const app  = createApp();
+  const pool = new SSEPool();
+
+  // ---- SSE endpoint ----
+  app.get('/__zq_reload', (req, res) => {
+    const sse = res.sse({ keepAlive: 30000, keepAliveComment: 'ping' });
+    pool.add(sse);
+  });
+
+  // ---- Auto-resolve zquery.min.js ----
+  const pkgRoot = path.resolve(__dirname, '..', '..', '..');
+
+  app.use((req, res, next) => {
+    if (noIntercept) return next();
+    const basename = path.basename(req.url.split('?')[0]).toLowerCase();
+    if (basename !== 'zquery.min.js') return next();
+
+    const candidates = [
+      path.join(pkgRoot, 'dist', 'zquery.min.js'),
+      path.join(root, 'node_modules', 'zero-query', 'dist', 'zquery.min.js'),
+    ];
+    for (const p of candidates) {
+      if (fs.existsSync(p)) {
+        res.set('Content-Type', 'application/javascript; charset=utf-8');
+        res.set('Cache-Control', 'no-cache');
+        res.send(fs.readFileSync(p, 'utf-8'));
+        return;
+      }
+    }
+    next();
+  });
+
+  // ---- Static files ----
+  app.use(serveStatic(root, { index: false, dotfiles: 'ignore' }));
+
+  // ---- SPA fallback — inject overlay/SSE snippet ----
+  app.get('*', (req, res) => {
+    if (path.extname(req.url) && path.extname(req.url) !== '.html') {
+      res.status(404).send('Not Found');
+      return;
+    }
+    const indexPath = path.join(root, htmlEntry);
+    if (!fs.existsSync(indexPath)) {
+      res.status(404).send(`${htmlEntry} not found`);
+      return;
+    }
+    let html = fs.readFileSync(indexPath, 'utf-8');
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', OVERLAY_SCRIPT + '\n</body>');
+    } else {
+      html += OVERLAY_SCRIPT;
+    }
+    res.html(html);
+  });
+
+  function listen(cb) {
+    app.listen(port, cb);
+  }
+
+  return { app, pool, listen };
+}
+
+module.exports = { createServer, SSEPool };

package/cli/commands/dev/validator.js

@@ -0,0 +1,94 @@
+/**
+ * cli/commands/dev/validator.js — JS syntax validation
+ *
+ * Pre-validates JavaScript files on save using Node's VM module.
+ * Returns structured error descriptors with code frames compatible
+ * with the browser error overlay.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const vm = require('vm');
+
+// ---------------------------------------------------------------------------
+// Code frame generator
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a code frame showing ~4 lines of context around the error
+ * with a caret pointer at the offending column.
+ *
+ * @param {string} source   — full file contents
+ * @param {number} line     — 1-based line number
+ * @param {number} column   — 1-based column number
+ * @returns {string}
+ */
+function generateCodeFrame(source, line, column) {
+  const lines = source.split('\n');
+  const start = Math.max(0, line - 4);
+  const end   = Math.min(lines.length, line + 3);
+  const pad   = String(end).length;
+  const frame = [];
+
+  for (let i = start; i < end; i++) {
+    const num    = String(i + 1).padStart(pad);
+    const marker = i === line - 1 ? '>' : ' ';
+    frame.push(`${marker} ${num} | ${lines[i]}`);
+    if (i === line - 1 && column > 0) {
+      frame.push(`  ${' '.repeat(pad)} | ${' '.repeat(column - 1)}^`);
+    }
+  }
+  return frame.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// JS validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a JavaScript file for syntax errors.
+ *
+ * Strips ESM import/export statements (preserving line numbers) so the
+ * VM can parse module-style code, then compiles via vm.Script.
+ *
+ * @param {string} filePath — absolute path to the file
+ * @param {string} relPath  — display-friendly relative path
+ * @returns {object|null}   — error descriptor, or null if valid
+ */
+function validateJS(filePath, relPath) {
+  let source;
+  try { source = fs.readFileSync(filePath, 'utf-8'); } catch { return null; }
+
+  const normalized = source.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const stripped = normalized.split('\n').map(line => {
+    if (/^\s*import\s+.*from\s+['"]/.test(line))  return ' '.repeat(line.length);
+    if (/^\s*import\s+['"]/.test(line))            return ' '.repeat(line.length);
+    if (/^\s*export\s*\{/.test(line))              return ' '.repeat(line.length);
+    line = line.replace(/^(\s*)export\s+default\s+/, '$1');
+    line = line.replace(/^(\s*)export\s+(const|let|var|function|class|async\s+function)\s/, '$1$2 ');
+    line = line.replace(/import\.meta\.url/g, "'__meta__'");
+    line = line.replace(/import\.meta/g, '({})');
+    return line;
+  }).join('\n');
+
+  try {
+    new vm.Script(stripped, { filename: relPath });
+    return null;
+  } catch (err) {
+    const line   = err.stack ? parseInt((err.stack.match(/:(\d+)/) || [])[1]) || 0 : 0;
+    const col    = err.stack ? parseInt((err.stack.match(/:(\d+):(\d+)/) || [])[2]) || 0 : 0;
+    const frame  = line > 0 ? generateCodeFrame(source, line, col) : '';
+    return {
+      code:    'ZQ_DEV_SYNTAX',
+      type:    err.constructor.name || 'SyntaxError',
+      message: err.message,
+      file:    relPath,
+      line,
+      column:  col,
+      frame,
+    };
+  }
+}
+
+module.exports = { generateCodeFrame, validateJS };

package/cli/commands/dev/watcher.js

@@ -0,0 +1,114 @@
+/**
+ * cli/commands/dev/watcher.js — File system watcher
+ *
+ * Recursively watches the project root for file changes, validates
+ * JS files for syntax errors, and broadcasts reload / CSS hot-swap /
+ * error events through the SSE pool.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { validateJS }                      = require('./validator');
+const { logCSS, logReload, logError }     = require('./logger');
+
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.cache']);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function shouldWatch(filename) {
+  return !!filename && !filename.startsWith('.');
+}
+
+function isIgnored(filepath) {
+  return filepath.split(path.sep).some(p => IGNORE_DIRS.has(p));
+}
+
+/** Recursively collect every directory under `dir` (excluding ignored). */
+function collectWatchDirs(dir) {
+  const dirs = [dir];
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || IGNORE_DIRS.has(entry.name)) continue;
+      dirs.push(...collectWatchDirs(path.join(dir, entry.name)));
+    }
+  } catch { /* unreadable dir — skip */ }
+  return dirs;
+}
+
+// ---------------------------------------------------------------------------
+// Watcher factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Start watching `root` for file changes.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.root  — absolute project root
+ * @param {SSEPool} opts.pool  — SSE broadcast pool
+ * @returns {{ dirs: string[], destroy: Function }}
+ */
+function startWatcher({ root, pool }) {
+  const watchDirs = collectWatchDirs(root);
+  const watchers  = [];
+
+  let debounceTimer;
+  let currentError = null;   // track which file has an active error
+
+  for (const dir of watchDirs) {
+    try {
+      const watcher = fs.watch(dir, (_, filename) => {
+        if (!shouldWatch(filename)) return;
+        const fullPath = path.join(dir, filename || '');
+        if (isIgnored(fullPath)) return;
+
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          const rel = path.relative(root, fullPath).replace(/\\/g, '/');
+          const ext = path.extname(filename).toLowerCase();
+
+          // ---- CSS hot-swap ----
+          if (ext === '.css') {
+            logCSS(rel);
+            pool.broadcast('css', rel);
+            return;
+          }
+
+          // ---- JS syntax check ----
+          if (ext === '.js') {
+            const err = validateJS(fullPath, rel);
+            if (err) {
+              currentError = rel;
+              logError(err);
+              pool.broadcast('error:syntax', JSON.stringify(err));
+              return;
+            }
+            // File was fixed — clear previous overlay
+            if (currentError === rel) {
+              currentError = null;
+              pool.broadcast('error:clear', '');
+            }
+          }
+
+          // ---- Full reload ----
+          logReload(rel);
+          pool.broadcast('reload', rel);
+        }, 100);
+      });
+      watchers.push(watcher);
+    } catch { /* dir became inaccessible — skip */ }
+  }
+
+  function destroy() {
+    clearTimeout(debounceTimer);
+    watchers.forEach(w => w.close());
+  }
+
+  return { dirs: watchDirs, destroy };
+}
+
+module.exports = { startWatcher, collectWatchDirs };