zero-query 1.0.9 → 1.2.0

package/cli/commands/dev/watcher.js

@@ -1,172 +1,172 @@
-/**
- * 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));
-}
-
-/**
- * Return the file's mtime as a millisecond timestamp, or 0 if unreadable.
- * Used to ignore spurious fs.watch events (Windows fires on reads too).
- */
-function mtime(filepath) {
-  try { return fs.statSync(filepath).mtimeMs; } catch { return 0; }
-}
-
-/** 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, bundleMode, serveRoot }) {
-  const watchDirs = collectWatchDirs(root);
-  const watchers  = [];
-
-  let debounceTimer;
-  let currentError = null;   // track which file has an active error
-  let bundleTimer = null;    // debounce for bundle rebuilds
-
-  // Track file mtimes so we only react to genuine writes.
-  // On Windows, fs.watch fires on reads/access too, which causes
-  // spurious reloads the first time the server serves a file.
-  // We seed the cache with current mtimes so the first real save
-  // (which changes the mtime) is always detected.
-  const mtimeCache = new Map();
-  for (const d of watchDirs) {
-    try {
-      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
-        if (entry.isFile()) {
-          const fp = path.join(d, entry.name);
-          const mt = mtime(fp);
-          if (mt) mtimeCache.set(fp, mt);
-        }
-      }
-    } catch { /* skip */ }
-  }
-
-  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(() => {
-          // Skip if the file hasn't actually been modified
-          const mt = mtime(fullPath);
-          if (mt === 0) return;                 // deleted or unreadable
-          const prev = mtimeCache.get(fullPath);
-          mtimeCache.set(fullPath, mt);
-          if (prev !== undefined && mt === prev) return; // unchanged
-
-          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 ----
-          if (bundleMode) {
-            // Debounce bundle rebuilds (500ms) so rapid saves don't spam
-            clearTimeout(bundleTimer);
-            bundleTimer = setTimeout(() => {
-              try {
-                const bundleFn = require('../bundle');
-                const { args: cliArgs } = require('../../args');
-                const savedArgs = cliArgs.slice();
-                cliArgs.length = 0;
-                cliArgs.push('bundle');
-                const prevCwd = process.cwd();
-                process.chdir(root);
-                bundleFn();
-                process.chdir(prevCwd);
-                cliArgs.length = 0;
-                savedArgs.forEach(a => cliArgs.push(a));
-                logReload(rel + ' (rebuilt)');
-                pool.broadcast('reload', rel);
-              } catch (err) {
-                console.error('  Bundle rebuild failed:', err.message);
-              }
-            }, 500);
-            return;
-          }
-          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 };
+/**
+ * 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));
+}
+
+/**
+ * Return the file's mtime as a millisecond timestamp, or 0 if unreadable.
+ * Used to ignore spurious fs.watch events (Windows fires on reads too).
+ */
+function mtime(filepath) {
+  try { return fs.statSync(filepath).mtimeMs; } catch { return 0; }
+}
+
+/** 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, bundleMode, serveRoot }) {
+  const watchDirs = collectWatchDirs(root);
+  const watchers  = [];
+
+  let debounceTimer;
+  let currentError = null;   // track which file has an active error
+  let bundleTimer = null;    // debounce for bundle rebuilds
+
+  // Track file mtimes so we only react to genuine writes.
+  // On Windows, fs.watch fires on reads/access too, which causes
+  // spurious reloads the first time the server serves a file.
+  // We seed the cache with current mtimes so the first real save
+  // (which changes the mtime) is always detected.
+  const mtimeCache = new Map();
+  for (const d of watchDirs) {
+    try {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        if (entry.isFile()) {
+          const fp = path.join(d, entry.name);
+          const mt = mtime(fp);
+          if (mt) mtimeCache.set(fp, mt);
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  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(() => {
+          // Skip if the file hasn't actually been modified
+          const mt = mtime(fullPath);
+          if (mt === 0) return;                 // deleted or unreadable
+          const prev = mtimeCache.get(fullPath);
+          mtimeCache.set(fullPath, mt);
+          if (prev !== undefined && mt === prev) return; // unchanged
+
+          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 ----
+          if (bundleMode) {
+            // Debounce bundle rebuilds (500ms) so rapid saves don't spam
+            clearTimeout(bundleTimer);
+            bundleTimer = setTimeout(() => {
+              try {
+                const bundleFn = require('../bundle');
+                const { args: cliArgs } = require('../../args');
+                const savedArgs = cliArgs.slice();
+                cliArgs.length = 0;
+                cliArgs.push('bundle');
+                const prevCwd = process.cwd();
+                process.chdir(root);
+                bundleFn();
+                process.chdir(prevCwd);
+                cliArgs.length = 0;
+                savedArgs.forEach(a => cliArgs.push(a));
+                logReload(rel + ' (rebuilt)');
+                pool.broadcast('reload', rel);
+              } catch (err) {
+                console.error('  Bundle rebuild failed:', err.message);
+              }
+            }, 500);
+            return;
+          }
+          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 };

package/cli/help.js

@@ -1,112 +1,114 @@
-// cli/help.js - show CLI usage information
-
-function showHelp() {
-  console.log(`
-  zQuery CLI \u2014 create, dev, bundle & build
-
-  COMMANDS
-
-    create [dir]               Scaffold a new zQuery project
-                               Creates index.html, global.css, app/, assets/ in the target directory
-                               (defaults to the current directory)
-      --minimal, -m            Use the minimal template (home, counter, about)
-                               instead of the full-featured default scaffold
-      --ssr, -s                Use the SSR template - includes server/index.js
-                               SSR HTTP server with shared component definitions,
-                               blog with param routing, JSON API, and SEO metadata
-
-    dev [root]                 Start a dev server with live-reload
-      --port, -p <number>     Port number (default: 3100)
-      --index, -i <file>        Index HTML file (default: index.html)
-      --no-intercept           Disable auto-resolution of zquery.min.js
-                               (serve the on-disk vendor copy instead)
-      --bundle, -b             Serve the bundled build (runs bundler first,
-                               serves from dist/server/, auto-rebuilds on save)
-
-                               Includes error overlay: syntax errors are
-                               caught on save and shown as a full-screen
-                               overlay in the browser. Runtime errors and
-                               unhandled rejections are also captured.
-
-    bundle [dir|file]          Bundle app ES modules into a single file
-      --out, -o <path>         Output directory (default: dist/ next to HTML file)
-      --index, -i <file>        Index HTML file (default: auto-detected)
-      --minimal, -m            Only output HTML, bundled JS, and global CSS (skip static assets)
-      --global-css <path>      Override global CSS input (default: first <link> in HTML)
-
-    build                      Build the zQuery library \u2192 dist/      --watch, -w              Watch src/ and rebuild on changes                               (must be run from the project root where src/ lives)
-
-  SMART DEFAULTS
-
-    The bundler works with zero flags for typical projects:
-      \u2022 Entry is auto-detected with strict precedence:
-        1. index.html first, then other .html files
-        2. Within HTML: module script pointing to app.js, else first module script
-        3. JS scan: $.router( first (entry point), then $.mount( / $.store(
-        4. Convention fallbacks (app/app.js, scripts/app.js, app.js, etc.)
-      • Passing a directory auto-detects the entry; passing a file uses it directly
-      • zquery.min.js is always embedded (auto-built from source if not found)
-      • HTML file is auto-detected (any .html, not just index.html)
-      • Output goes to dist/server/ and dist/local/ next to the detected HTML file
-
-  OUTPUT
-
-    The bundler produces two self-contained sub-directories:
-
-      dist/server/               deploy to your web server
-        index.html               has <base href="/"> for SPA deep routes
-        z-<entry>.<hash>.js      readable bundle
-        z-<entry>.<hash>.min.js  minified bundle
-
-      dist/local/                open from disk (file://)
-        index.html               relative paths, no <base> tag
-        z-<entry>.<hash>.js      same bundle
-
-    Previous hashed builds are automatically cleaned on each rebuild.
-
-  DEVELOPMENT
-
-    zquery dev                 start a dev server with live-reload (port 3100)
-    zquery dev --port 8080     custom port
-
-    The dev server includes a full-screen error overlay:
-      • JS files are syntax-checked on save - errors block reload
-        and show an overlay with exact file, line:column, and code frame
-      • Runtime errors and unhandled rejections are also captured
-      • The overlay auto-clears when the file is fixed and saved
-      • Press Esc or click × to dismiss manually
-
-  EXAMPLES
-
-    # Scaffold a new project and start developing
-    zquery create my-app && zquery dev my-app
-
-    # Start dev server with live-reload
-    zquery dev my-app
-
-    # Build the library only
-    zquery build
-
-    # Bundle an app from the project root
-    zquery bundle my-app/
-
-    # Pass a direct entry file (skip auto-detection)
-    zquery bundle my-app/app/main.js
-
-    # Custom output directory
-    zquery bundle my-app/ -o build/
-
-    # Minimal build (HTML + JS + global CSS, no static asset copying)
-    zquery bundle my-app/ --minimal
-
-    # Dev server with a custom index page
-    zquery dev my-app/ --index home.html
-
-  The bundler walks the ES module import graph starting from the entry
-  file, topologically sorts dependencies, strips import/export syntax,
-  and concatenates everything into a single IIFE with content-hashed
-  filenames for cache-busting. No dependencies needed \u2014 just Node.js.
-`);
-}
-
-module.exports = showHelp;
+// cli/help.js - show CLI usage information
+
+function showHelp() {
+  console.log(`
+  zQuery CLI \u2014 create, dev, bundle & build
+
+  COMMANDS
+
+    create [dir]               Scaffold a new zQuery project
+                               Creates index.html, global.css, app/, assets/ in the target directory
+                               (defaults to the current directory)
+      --minimal, -m            Use the minimal template (home, counter, about)
+                               instead of the full-featured default scaffold
+      --ssr, -s                Use the SSR template - includes server/index.js
+                               SSR HTTP server with shared component definitions,
+                               blog with param routing, JSON API, and SEO metadata
+      --webrtc-demo, -w        Use the WebRTC demo template - one-page video room
+                               powered by $.webrtc.join() against a zero-server hub
+
+    dev [root]                 Start a dev server with live-reload
+      --port, -p <number>     Port number (default: 3100)
+      --index, -i <file>        Index HTML file (default: index.html)
+      --no-intercept           Disable auto-resolution of zquery.min.js
+                               (serve the on-disk vendor copy instead)
+      --bundle, -b             Serve the bundled build (runs bundler first,
+                               serves from dist/server/, auto-rebuilds on save)
+
+                               Includes error overlay: syntax errors are
+                               caught on save and shown as a full-screen
+                               overlay in the browser. Runtime errors and
+                               unhandled rejections are also captured.
+
+    bundle [dir|file]          Bundle app ES modules into a single file
+      --out, -o <path>         Output directory (default: dist/ next to HTML file)
+      --index, -i <file>        Index HTML file (default: auto-detected)
+      --minimal, -m            Only output HTML, bundled JS, and global CSS (skip static assets)
+      --global-css <path>      Override global CSS input (default: first <link> in HTML)
+
+    build                      Build the zQuery library \u2192 dist/      --watch, -w              Watch src/ and rebuild on changes                               (must be run from the project root where src/ lives)
+
+  SMART DEFAULTS
+
+    The bundler works with zero flags for typical projects:
+      \u2022 Entry is auto-detected with strict precedence:
+        1. index.html first, then other .html files
+        2. Within HTML: module script pointing to app.js, else first module script
+        3. JS scan: $.router( first (entry point), then $.mount( / $.store(
+        4. Convention fallbacks (app/app.js, scripts/app.js, app.js, etc.)
+      • Passing a directory auto-detects the entry; passing a file uses it directly
+      • zquery.min.js is always embedded (auto-built from source if not found)
+      • HTML file is auto-detected (any .html, not just index.html)
+      • Output goes to dist/server/ and dist/local/ next to the detected HTML file
+
+  OUTPUT
+
+    The bundler produces two self-contained sub-directories:
+
+      dist/server/               deploy to your web server
+        index.html               has <base href="/"> for SPA deep routes
+        z-<entry>.<hash>.js      readable bundle
+        z-<entry>.<hash>.min.js  minified bundle
+
+      dist/local/                open from disk (file://)
+        index.html               relative paths, no <base> tag
+        z-<entry>.<hash>.js      same bundle
+
+    Previous hashed builds are automatically cleaned on each rebuild.
+
+  DEVELOPMENT
+
+    zquery dev                 start a dev server with live-reload (port 3100)
+    zquery dev --port 8080     custom port
+
+    The dev server includes a full-screen error overlay:
+      • JS files are syntax-checked on save - errors block reload
+        and show an overlay with exact file, line:column, and code frame
+      • Runtime errors and unhandled rejections are also captured
+      • The overlay auto-clears when the file is fixed and saved
+      • Press Esc or click × to dismiss manually
+
+  EXAMPLES
+
+    # Scaffold a new project and start developing
+    zquery create my-app && zquery dev my-app
+
+    # Start dev server with live-reload
+    zquery dev my-app
+
+    # Build the library only
+    zquery build
+
+    # Bundle an app from the project root
+    zquery bundle my-app/
+
+    # Pass a direct entry file (skip auto-detection)
+    zquery bundle my-app/app/main.js
+
+    # Custom output directory
+    zquery bundle my-app/ -o build/
+
+    # Minimal build (HTML + JS + global CSS, no static asset copying)
+    zquery bundle my-app/ --minimal
+
+    # Dev server with a custom index page
+    zquery dev my-app/ --index home.html
+
+  The bundler walks the ES module import graph starting from the entry
+  file, topologically sorts dependencies, strips import/export syntax,
+  and concatenates everything into a single IIFE with content-hashed
+  filenames for cache-busting. No dependencies needed \u2014 just Node.js.
+`);
+}
+
+module.exports = showHelp;