zero-query 0.2.5 → 0.2.8

package/cli.js

@@ -3,8 +3,9 @@
 /**
  * zQuery CLI
  *
- * Zero-dependency command-line tool for building the zQuery library
- * and bundling zQuery-based applications into a single file.
+ * Zero-dependency command-line tool for building the zQuery library,
+ * bundling zQuery-based applications, and running a dev server with
+ * live-reload.
  *
  * Usage:
  *   zquery build                      Build the zQuery library (dist/)
@@ -13,7 +14,9 @@
  *   zquery bundle scripts/app.js      Specify entry explicitly
  *   zquery bundle -o build/           Custom output directory
  *   zquery bundle --html other.html   Use a specific HTML file instead of auto-detected
- *   zquery bundle --watch             Watch & rebuild on changes
+ *
+ *   zquery dev [root]                 Start dev server with live-reload
+ *   zquery dev --port 8080            Custom port (default: 3100)
  *
  * Smart defaults (no flags needed for typical projects):
  *   - Entry is auto-detected from index.html's <script type="module" src="...">
@@ -24,6 +27,7 @@
  * Examples:
  *   cd my-app && npx zero-query bundle              # just works!
  *   npx zero-query bundle path/to/scripts/app.js     # works from anywhere
+ *   cd my-app && npx zquery dev                       # dev server with live-reload
  */
 
 const fs     = require('fs');
@@ -412,7 +416,6 @@ function bundleApp() {
   }
 
   const outPath    = option('out', 'o', null);
-  const watchMode  = flag('watch', 'w');
 
   // Auto-detect index.html by walking up from the entry file, then check cwd
   let htmlFile = option('html', null, null);
@@ -595,26 +598,6 @@ function bundleApp() {
   }
 
   doBuild();
-
-  // Watch mode
-  if (watchMode) {
-    const watchDirs = new Set();
-    const files = walkImportGraph(entry);
-    files.forEach(f => watchDirs.add(path.dirname(f)));
-
-    console.log('  Watching for changes...\n');
-    let debounceTimer;
-    for (const dir of watchDirs) {
-      fs.watch(dir, { recursive: true }, (_, filename) => {
-        if (!filename || !filename.endsWith('.js')) return;
-        clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(() => {
-          console.log(`  Changed: ${filename} — rebuilding...`);
-          try { doBuild(); } catch (e) { console.error(`  ✗ ${e.message}`); }
-        }, 200);
-      });
-    }
-  }
 }
 
 /**
@@ -745,23 +728,400 @@ function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFi
 }
 
 
+// ---------------------------------------------------------------------------
+// "dev" command — development server with live-reload
+// ---------------------------------------------------------------------------
+
+/**
+ * SSE live-reload client script injected into served HTML.
+ * Connects to /__zq_reload, reloads on 'reload' events,
+ * and hot-swaps CSS on 'css' events without a full reload.
+ */
+const LIVE_RELOAD_SNIPPET = `<script>
+(function(){
+  var es, timer;
+  function connect(){
+    es = new EventSource('/__zq_reload');
+    es.addEventListener('reload', function(){ location.reload(); });
+    es.addEventListener('css', function(e){
+      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.onerror = function(){
+      es.close();
+      clearTimeout(timer);
+      timer = setTimeout(connect, 2000);
+    };
+  }
+  connect();
+})();
+</script>`;
+
+function devServer() {
+  let zeroHttp;
+  try {
+    zeroHttp = require('zero-http');
+  } catch (_) {
+    console.error(`\n  ✗ 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;
+
+  // Determine the project root to serve
+  let root = null;
+  for (let i = 1; i < args.length; i++) {
+    if (!args[i].startsWith('-') && args[i - 1] !== '-p' && args[i - 1] !== '--port') {
+      root = path.resolve(process.cwd(), args[i]);
+      break;
+    }
+  }
+  if (!root) {
+    // Auto-detect: look for index.html in cwd or common sub-dirs
+    const candidates = [
+      process.cwd(),
+      path.join(process.cwd(), 'public'),
+      path.join(process.cwd(), 'src'),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(path.join(c, 'index.html'))) { root = c; break; }
+    }
+    if (!root) root = process.cwd();
+  }
+
+  const PORT = parseInt(option('port', 'p', '3100'));
+
+  // SSE clients for live-reload
+  const sseClients = new Set();
+
+  const app = createApp();
+
+  // SSE endpoint — clients connect here for reload notifications
+  app.get('/__zq_reload', (req, res) => {
+    const sse = res.sse({ keepAlive: 30000, keepAliveComment: 'ping' });
+    sseClients.add(sse);
+    sse.on('close', () => sseClients.delete(sse));
+  });
+
+  // Auto-resolve zquery.min.js — serve the freshest version regardless of
+  // what's on disk in the project.  Priority:
+  //   1. Package dist/ (when running from the repo after `npm run build`)
+  //   2. node_modules/zero-query/dist/ (when installed as a dependency)
+  //   3. Fall through to static serving (vendor copy on disk)
+  // Registered as middleware so it runs BEFORE serveStatic.
+  app.use((req, res, next) => {
+    const basename = path.basename(req.url.split('?')[0]).toLowerCase();
+    if (basename !== 'zquery.min.js') return next();
+
+    const candidates = [
+      path.join(__dirname, 'dist', 'zquery.min.js'),                // package repo
+      path.join(root, 'node_modules', 'zero-query', 'dist', 'zquery.min.js'), // npm dep
+    ];
+    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(); // fall through to static / 404
+  });
+
+  // Static file serving
+  app.use(serveStatic(root, { index: false, dotfiles: 'ignore' }));
+
+  // SPA fallback — inject live-reload snippet into HTML
+  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, 'index.html');
+    if (!fs.existsSync(indexPath)) {
+      res.status(404).send('index.html not found');
+      return;
+    }
+    let html = fs.readFileSync(indexPath, 'utf-8');
+    // Inject live-reload snippet before </body> or at end
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', LIVE_RELOAD_SNIPPET + '\n</body>');
+    } else {
+      html += LIVE_RELOAD_SNIPPET;
+    }
+    res.html(html);
+  });
+
+  // Broadcast a reload event to all connected SSE clients
+  function broadcast(eventType, data) {
+    for (const sse of sseClients) {
+      try { sse.event(eventType, data || ''); } catch (_) { sseClients.delete(sse); }
+    }
+  }
+
+  // File watcher — watch the project root for changes
+  const WATCH_EXTS = new Set(['.js', '.css', '.html', '.htm', '.json', '.svg']);
+  const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.cache']);
+  let debounceTimer;
+
+  function shouldWatch(filename) {
+    if (!filename) return false;
+    const ext = path.extname(filename).toLowerCase();
+    return WATCH_EXTS.has(ext);
+  }
+
+  function isIgnored(filepath) {
+    const parts = filepath.split(path.sep);
+    return parts.some(p => IGNORE_DIRS.has(p));
+  }
+
+  // Collect directories to watch (walk root, skip ignored)
+  function collectWatchDirs(dir) {
+    const dirs = [dir];
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (IGNORE_DIRS.has(entry.name)) continue;
+        const sub = path.join(dir, entry.name);
+        dirs.push(...collectWatchDirs(sub));
+      }
+    } catch (_) {}
+    return dirs;
+  }
+
+  const watchDirs = collectWatchDirs(root);
+  const watchers = [];
+
+  for (const dir of watchDirs) {
+    try {
+      const watcher = fs.watch(dir, (eventType, 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();
+          const now = new Date().toLocaleTimeString();
+
+          if (ext === '.css') {
+            console.log(`  ${now}  \x1b[35m css \x1b[0m ${rel}`);
+            broadcast('css', rel);
+          } else {
+            console.log(`  ${now}  \x1b[36m reload \x1b[0m ${rel}`);
+            broadcast('reload', rel);
+          }
+        }, 100);
+      });
+      watchers.push(watcher);
+    } catch (_) {}
+  }
+
+  app.listen(PORT, () => {
+    console.log(`\n  \x1b[1mzQuery Dev Server\x1b[0m`);
+    console.log(`  \x1b[2m${'─'.repeat(40)}\x1b[0m`);
+    console.log(`  Local:       \x1b[36mhttp://localhost:${PORT}/\x1b[0m`);
+    console.log(`  Root:        ${path.relative(process.cwd(), root) || '.'}`);
+    console.log(`  Live Reload: \x1b[32menabled\x1b[0m (SSE)`);
+    console.log(`  Watching:    ${WATCH_EXTS.size} file types in ${watchDirs.length} director${watchDirs.length === 1 ? 'y' : 'ies'}`);
+    console.log(`  \x1b[2m${'─'.repeat(40)}\x1b[0m`);
+    console.log(`  Press Ctrl+C to stop\n`);
+  });
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n  Shutting down...');
+    watchers.forEach(w => w.close());
+    for (const sse of sseClients) { try { sse.close(); } catch (_) {} }
+    app.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1000);
+  });
+}
+
+
+// ---------------------------------------------------------------------------
+// Create — scaffold a new zQuery project
+// ---------------------------------------------------------------------------
+
+function createProject() {
+  const target = args[1] ? path.resolve(args[1]) : process.cwd();
+  const name   = path.basename(target);
+
+  // Guard: refuse to overwrite existing files
+  const conflicts = ['index.html', 'scripts'].filter(f =>
+    fs.existsSync(path.join(target, f))
+  );
+  if (conflicts.length) {
+    console.error(`\n  ✗ Directory already contains: ${conflicts.join(', ')}`);
+    console.error(`  Aborting to avoid overwriting existing files.\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n  zQuery — Create Project\n`);
+  console.log(`  Scaffolding into ${target}\n`);
+
+  // ---- templates ----
+
+  const indexHTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${name}</title>
+  <link rel="stylesheet" href="styles/styles.css">
+  <script src="scripts/vendor/zQuery.min.js"></script>
+  <script type="module" src="scripts/app.js"></script>
+</head>
+<body>
+  <nav>
+    <a z-link="/">Home</a>
+    <a z-link="/about">About</a>
+  </nav>
+  <div id="app"></div>
+</body>
+</html>`;
+
+  const appJS = `// scripts/app.js — entry point
+import './components/home.js';
+import './components/about.js';
+import { routes } from './routes.js';
+
+$.router({ el: '#app', routes, fallback: 'not-found' });
+
+$.ready(() => {
+  console.log('zQuery v' + $.version + ' loaded');
+});`;
+
+  const routesJS = `// scripts/routes.js
+export const routes = [
+  { path: '/',      component: 'home-page'  },
+  { path: '/about', component: 'about-page' },
+];`;
+
+  const homeJS = `// scripts/components/home.js
+$.component('home-page', {
+  state: () => ({ count: 0 }),
+
+  increment() { this.state.count++; },
+
+  render() {
+    return \`
+      <h1>Home</h1>
+      <p>Count: \${this.state.count}</p>
+      <button @click="increment">+1</button>
+    \`;
+  }
+});`;
+
+  const aboutJS = `// scripts/components/about.js
+$.component('about-page', {
+  render() {
+    return \`
+      <h1>About</h1>
+      <p>Built with <strong>zQuery</strong> — a lightweight, zero-dependency frontend library.</p>
+    \`;
+  }
+});`;
+
+  const stylesCSS = `/* styles/styles.css */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.6;
+  color: #e6edf3;
+  background: #0d1117;
+  padding: 2rem;
+}
+
+nav {
+  display: flex;
+  gap: 1rem;
+  margin-bottom: 2rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid #30363d;
+}
+
+nav a {
+  color: #58a6ff;
+  text-decoration: none;
+  font-weight: 500;
+}
+
+nav a:hover { text-decoration: underline; }
+
+h1 { margin-bottom: 0.5rem; }
+
+button {
+  margin-top: 0.75rem;
+  padding: 0.5rem 1.25rem;
+  background: #238636;
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 0.95rem;
+}
+
+button:hover { background: #2ea043; }`;
+
+  // ---- write files ----
+
+  const files = {
+    'index.html':                  indexHTML,
+    'scripts/app.js':              appJS,
+    'scripts/routes.js':           routesJS,
+    'scripts/components/home.js':  homeJS,
+    'scripts/components/about.js': aboutJS,
+    'styles/styles.css':           stylesCSS,
+  };
+
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(target, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf-8');
+    console.log(`  ✓ ${rel}`);
+  }
+
+  console.log(`
+  Done! Next steps:
+
+    ${target !== process.cwd() ? `cd ${args[1]}\n    ` : ''}npx zquery dev
+`);
+}
+
+
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
 
 function showHelp() {
   console.log(`
-  zQuery CLI — build & bundle tool
+  zQuery CLI — create, dev, bundle & build
 
   COMMANDS
 
-    build                      Build the zQuery library → dist/
-                               (must be run from the project root where src/ lives)
+    create [dir]               Scaffold a new zQuery project
+                               Creates index.html, scripts/, styles/ in the target directory
+                               (defaults to the current directory)
+
+    dev [root]                 Start a dev server with live-reload
+      --port, -p <number>     Port number (default: 3100)
 
     bundle [entry]             Bundle app ES modules into a single file
       --out, -o <path>         Output directory (default: dist/ next to index.html)
       --html <file>            Use a specific HTML file (default: auto-detected)
-      --watch, -w              Watch source files and rebuild on changes
+
+    build                      Build the zQuery library → dist/
+                               (must be run from the project root where src/ lives)
 
   SMART DEFAULTS
 
@@ -788,11 +1148,17 @@ function showHelp() {
 
   DEVELOPMENT
 
-    npm run serve              start a local dev server (zero-http, SPA routing)
-    npm run dev                watch mode — auto-rebuild bundle on source changes
+    zquery dev                 start a dev server with live-reload (port 3100)
+    zquery dev --port 8080     custom port
 
   EXAMPLES
 
+    # Scaffold a new project and start developing
+    zquery create my-app && cd my-app && zquery dev
+
+    # Start dev server with live-reload
+    cd my-app && zquery dev
+
     # Build the library only
     zquery build
 
@@ -805,9 +1171,6 @@ function showHelp() {
     # Custom output directory
     zquery bundle -o build/
 
-    # Watch mode
-    zquery bundle --watch
-
   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
@@ -822,11 +1185,15 @@ function showHelp() {
 
 if (!command || command === '--help' || command === '-h' || command === 'help') {
   showHelp();
+} else if (command === 'create') {
+  createProject();
 } else if (command === 'build') {
   console.log('\n  zQuery Library Build\n');
   buildLibrary();
 } else if (command === 'bundle') {
   bundleApp();
+} else if (command === 'dev') {
+  devServer();
 } else {
   console.error(`\n  Unknown command: ${command}\n  Run "zquery --help" for usage.\n`);
   process.exit(1);

package/dist/zquery.js

@@ -1,5 +1,5 @@
 /**
- * zQuery (zeroQuery) v0.2.5
+ * zQuery (zeroQuery) v0.2.8
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman — MIT License
@@ -2576,7 +2576,7 @@ $.session    = session;
 $.bus        = bus;
 
 // --- Meta ------------------------------------------------------------------
-$.version = '0.2.5';
+$.version = '0.2.8';
 $.meta    = {};                // populated at build time by CLI bundler
 
 $.noConflict = () => {

package/dist/zquery.min.js

@@ -1,5 +1,5 @@
 /**
- * zQuery (zeroQuery) v0.2.5
+ * zQuery (zeroQuery) v0.2.8
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman — MIT License
@@ -13,5 +13,5 @@ class Router { constructor(config = {}) { this._el = null; const isFile = typeof
 class Store { constructor(config = {}) { this._subscribers = new Map(); this._wildcards = new Set(); this._actions = config.actions || {}; this._getters = config.getters || {}; this._middleware = []; this._history = []; this._debug = config.debug || false; const initial = typeof config.state === 'function' ? config.state() : { ...(config.state || {}) }; this.state = reactive(initial, (key, value, old) => { const subs = this._subscribers.get(key); if (subs) subs.forEach(fn => fn(value, old, key)); this._wildcards.forEach(fn => fn(key, value, old)); }); this.getters = {}; for (const [name, fn] of Object.entries(this._getters)) { Object.defineProperty(this.getters, name, { get: () => fn(this.state.__raw || this.state), enumerable: true }); } } dispatch(name, ...args) { const action = this._actions[name]; if (!action) { console.warn(`zQuery Store: Unknown action "${name}"`); return; } for (const mw of this._middleware) { const result = mw(name, args, this.state); if (result === false) return; } if (this._debug) { console.log(`%c[Store] ${name}`, 'color: #4CAF50; font-weight: bold;', ...args); } const result = action(this.state, ...args); this._history.push({ action: name, args, timestamp: Date.now() }); return result; } subscribe(keyOrFn, fn) { if (typeof keyOrFn === 'function') { this._wildcards.add(keyOrFn); return () => this._wildcards.delete(keyOrFn); } if (!this._subscribers.has(keyOrFn)) { this._subscribers.set(keyOrFn, new Set()); } this._subscribers.get(keyOrFn).add(fn); return () => this._subscribers.get(keyOrFn)?.delete(fn); } snapshot() { return JSON.parse(JSON.stringify(this.state.__raw || this.state)); } replaceState(newState) { const raw = this.state.__raw || this.state; for (const key of Object.keys(raw)) { delete this.state[key]; } Object.assign(this.state, newState); } use(fn) { this._middleware.push(fn); return this; } get history() { return [...this._history]; } reset(initialState) { this.replaceState(initialState); this._history = []; }
 const _config = { baseURL: '', headers: { 'Content-Type': 'application/json' }, timeout: 30000,
 function debounce(fn, ms = 250) { let timer; const debounced = (...args) => { clearTimeout(timer); timer = setTimeout(() => fn(...args), ms); }; debounced.cancel = () => clearTimeout(timer); return debounced;
-function $(selector, context) { if (typeof selector === 'function') { query.ready(selector); return; } return query(selector, context);
+function $(selector, context) { if (typeof selector === 'function') { query.ready(selector); return; } return query(selector, context);
 })(typeof window !== 'undefined' ? window : globalThis);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "description": "Lightweight modern frontend library — jQuery-like selectors, reactive components, SPA router, and state management with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -18,8 +18,7 @@
   ],
   "scripts": {
     "build": "node build.js",
-    "dev": "npx zquery bundle examples/starter-app/scripts/app.js --watch",
-    "serve": "node examples/starter-app/local-server.js",
+    "dev": "node cli.js dev examples/starter-app",
     "dev-lib": "node build.js --watch",
     "bundle": "node cli.js bundle",
     "bundle:app": "node cli.js bundle examples/starter-app/scripts/app.js"