bitwrench 2.0.15 → 2.0.16

package/src/bwserve/index.js

@@ -0,0 +1,352 @@
+/**
+ * bwserve — Server-driven UI library for bitwrench
+ *
+ * Programmatic API for building server-push UIs (Streamlit-style).
+ * Uses SSE (Server-Sent Events) by default, with WebSocket opt-in.
+ * Zero runtime dependencies — only Node.js stdlib (http, fs, path).
+ *
+ * Usage:
+ *   import bwserve from 'bitwrench/bwserve';
+ *   const app = bwserve.create({ port: 7902 });
+ *   app.page('/', (client) => {
+ *     client.render('#app', bw.makeCard({ title: 'Hello' }));
+ *   });
+ *   app.listen();
+ *
+ * @module bwserve
+ */
+
+import { BwServeClient } from './client.js';
+import { generateShell } from './shell.js';
+
+// Resolve dist/ paths relative to the package root
+import { fileURLToPath } from 'url';
+import { dirname, resolve, join, extname } from 'path';
+import { createServer } from 'http';
+import { readFileSync, existsSync, statSync } from 'fs';
+
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var DIST_DIR = resolve(__dirname, '..', '..', 'dist');
+
+// MIME type lookup for static file serving
+var MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf':  'font/ttf',
+  '.map':  'application/json'
+};
+
+/**
+ * Create a bwserve application.
+ *
+ * @param {Object} opts - Server options
+ * @param {number} [opts.port=7902] - Port to listen on
+ * @param {string} [opts.title='bwserve'] - Page title
+ * @param {string} [opts.static] - Directory to serve static files from
+ * @param {boolean} [opts.injectBitwrench=true] - Auto-inject bitwrench client JS
+ * @param {string|Object} [opts.theme] - Theme preset name or config object
+ * @returns {BwServeApp} Application instance
+ */
+export function create(opts) {
+  return new BwServeApp(opts || {});
+}
+
+/**
+ * BwServeApp — the server application object.
+ *
+ * Manages pages, client connections, and the HTTP/SSE server.
+ */
+class BwServeApp {
+  constructor(opts) {
+    this.port = opts.port || 7902;
+    this.title = opts.title || 'bwserve';
+    this.staticDir = opts.static || null;
+    this.injectBitwrench = opts.injectBitwrench !== false;
+    this.theme = opts.theme || null;
+    this.keepAliveInterval = opts.keepAliveInterval || 15000;
+    this._pages = new Map();
+    this._clients = new Map();
+    this._server = null;
+    this._clientCounter = 0;
+  }
+
+  /**
+   * Register a page handler.
+   *
+   * @param {string} path - URL path (e.g., '/', '/dashboard')
+   * @param {Function} handler - Called with (client: BwServeClient) on connection
+   * @returns {BwServeApp} this (for chaining)
+   */
+  page(path, handler) {
+    this._pages.set(path, handler);
+    return this;
+  }
+
+  /**
+   * Start the HTTP server and begin accepting SSE connections.
+   *
+   * @param {Function} [callback] - Called when server is listening
+   * @returns {Promise<void>}
+   */
+  listen(callback) {
+    var self = this;
+
+    return new Promise(function(res) {
+      self._server = createServer(function(req, rawRes) {
+        self._handleRequest(req, rawRes);
+      });
+
+      self._server.listen(self.port, function() {
+        if (callback) callback();
+        res();
+      });
+    });
+  }
+
+  /**
+   * Stop the server and close all client connections.
+   */
+  close() {
+    var self = this;
+    return new Promise(function(res) {
+      // Close all SSE streams
+      for (var record of self._clients.values()) {
+        if (record.client && typeof record.client.close === 'function') {
+          record.client.close();
+        }
+      }
+      self._clients.clear();
+
+      if (self._server) {
+        self._server.close(function() {
+          self._server = null;
+          res();
+        });
+      } else {
+        res();
+      }
+    });
+  }
+
+  /**
+   * Get count of active client connections.
+   * @returns {number}
+   */
+  get clientCount() {
+    return this._clients.size;
+  }
+
+  /**
+   * Broadcast a protocol message to all connected clients.
+   *
+   * If msg has a clientId field, send only to that client.
+   * Otherwise, broadcast to all.
+   *
+   * @param {Object} msg - Protocol message (replace, patch, append, remove, batch)
+   * @returns {number} Number of clients that received the message
+   */
+  broadcast(msg) {
+    if (msg.clientId) {
+      var record = this._clients.get(msg.clientId);
+      if (record && record.client) {
+        record.client._send(msg);
+        return 1;
+      }
+      return 0;
+    }
+    var count = 0;
+    for (var record of this._clients.values()) {
+      if (record.client && !record.client._closed) {
+        record.client._send(msg);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Internal: route incoming HTTP requests.
+   * @private
+   */
+  _handleRequest(req, res) {
+    var url = req.url || '/';
+    var method = req.method || 'GET';
+
+    // Parse URL path (strip query string)
+    var path = url.split('?')[0];
+
+    // /__bw/bitwrench.umd.js — serve bitwrench client library
+    if (path === '/__bw/bitwrench.umd.js' && method === 'GET') {
+      return this._serveDistFile(res, 'bitwrench.umd.js');
+    }
+
+    // /__bw/bitwrench.umd.min.js — serve minified
+    if (path === '/__bw/bitwrench.umd.min.js' && method === 'GET') {
+      return this._serveDistFile(res, 'bitwrench.umd.min.js');
+    }
+
+    // /__bw/bitwrench.css — serve bitwrench CSS
+    if (path === '/__bw/bitwrench.css' && method === 'GET') {
+      return this._serveDistFile(res, 'bitwrench.css');
+    }
+
+    // /__bw/events/:clientId — SSE stream
+    if (path.startsWith('/__bw/events/') && method === 'GET') {
+      var clientId = path.slice('/__bw/events/'.length);
+      return this._handleSSE(req, res, clientId);
+    }
+
+    // /__bw/action/:clientId — action POST
+    if (path.startsWith('/__bw/action/') && method === 'POST') {
+      var actionClientId = path.slice('/__bw/action/'.length);
+      return this._handleAction(req, res, actionClientId);
+    }
+
+    // Registered page routes — serve shell HTML
+    if (method === 'GET' && this._pages.has(path)) {
+      var clientId2 = 'c' + (++this._clientCounter);
+      var shell = generateShell({
+        clientId: clientId2,
+        title: this.title,
+        theme: this.theme,
+        injectBitwrench: this.injectBitwrench
+      });
+      // Store the page path for this client so SSE knows which handler to call
+      this._clients.set(clientId2, { pagePath: path, client: null });
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(shell);
+      return;
+    }
+
+    // Static file serving
+    if (method === 'GET' && this.staticDir) {
+      var filePath = join(this.staticDir, path);
+      if (existsSync(filePath) && statSync(filePath).isFile()) {
+        var ext = extname(filePath);
+        var mime = MIME_TYPES[ext] || 'application/octet-stream';
+        var content = readFileSync(filePath);
+        res.writeHead(200, { 'Content-Type': mime });
+        res.end(content);
+        return;
+      }
+    }
+
+    // 404
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  }
+
+  /**
+   * Serve a file from the dist/ directory.
+   * @private
+   */
+  _serveDistFile(res, filename) {
+    var filePath = join(DIST_DIR, filename);
+    if (!existsSync(filePath)) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not Found: ' + filename);
+      return;
+    }
+    var ext = extname(filename);
+    var mime = MIME_TYPES[ext] || 'application/octet-stream';
+    var content = readFileSync(filePath);
+    res.writeHead(200, {
+      'Content-Type': mime,
+      'Cache-Control': 'public, max-age=3600'
+    });
+    res.end(content);
+  }
+
+  /**
+   * Handle an SSE connection.
+   * @private
+   */
+  _handleSSE(req, res, clientId) {
+    var self = this;
+
+    // Set SSE headers
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*'
+    });
+
+    // Create client instance
+    var client = new BwServeClient(clientId, res);
+
+    // Look up the pending client record (set during page serve)
+    var pending = self._clients.get(clientId);
+    var pagePath = pending ? pending.pagePath : '/';
+    self._clients.set(clientId, { pagePath: pagePath, client: client });
+
+    // Keep-alive: send SSE comment periodically
+    var keepAlive = setInterval(function() {
+      if (!client._closed) {
+        try { res.write(':keepalive\n\n'); } catch (e) { /* ignore */ }
+      }
+    }, self.keepAliveInterval);
+
+    // Clean up on disconnect
+    req.on('close', function() {
+      clearInterval(keepAlive);
+      client._closed = true;
+      self._clients.delete(clientId);
+    });
+
+    // Call the page handler
+    var handler = self._pages.get(pagePath);
+    if (handler) {
+      try {
+        handler(client);
+      } catch (e) {
+        console.error('[bwserve] Page handler error:', e);
+      }
+    }
+  }
+
+  /**
+   * Handle an action POST from a client.
+   * @private
+   */
+  _handleAction(req, res, clientId) {
+    var record = this._clients.get(clientId);
+    if (!record || !record.client) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Unknown client' }));
+      return;
+    }
+
+    var body = '';
+    req.on('data', function(chunk) {
+      body += chunk;
+    });
+    req.on('end', function() {
+      try {
+        var data = JSON.parse(body);
+        var action = data.action;
+        var payload = data.data || data;
+        record.client._dispatch(action, payload);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+      } catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: e.message }));
+      }
+    });
+  }
+}
+
+export { BwServeApp, BwServeClient };
+
+export default { create, BwServeApp, BwServeClient };

package/src/bwserve/shell.js

@@ -0,0 +1,103 @@
+/**
+ * bwserve shell — generates the HTML page shell served to browsers.
+ *
+ * The shell is a minimal HTML doc that:
+ * - Loads bitwrench UMD + CSS from /__bw/ routes
+ * - Calls bw.loadDefaultStyles()
+ * - Optionally applies a theme
+ * - Creates a #app div
+ * - Opens an SSE connection via bw.clientConnect()
+ * - Delegates data-bw-action clicks to the server via POST
+ *
+ * @module bwserve/shell
+ */
+
+/**
+ * Generate the shell HTML page for a bwserve app.
+ *
+ * @param {Object} opts
+ * @param {string} opts.clientId - Unique client ID for this connection
+ * @param {string} [opts.title='bwserve'] - Page title
+ * @param {string} [opts.theme] - Theme preset name or config
+ * @param {boolean} [opts.injectBitwrench=true] - Whether to inject bitwrench scripts
+ * @returns {string} Complete HTML document
+ */
+export function generateShell(opts) {
+  opts = opts || {};
+  var clientId = opts.clientId || 'default';
+  var title = opts.title || 'bwserve';
+  var inject = opts.injectBitwrench !== false;
+
+  var head = [
+    '<!DOCTYPE html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="UTF-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1.0">',
+    '<title>' + title + '</title>'
+  ];
+
+  if (inject) {
+    head.push('<script src="/__bw/bitwrench.umd.js"></script>');
+    head.push('<link rel="stylesheet" href="/__bw/bitwrench.css">');
+  }
+
+  head.push('</head>');
+  head.push('<body>');
+  head.push('<div id="app"></div>');
+
+  var script = [
+    '<script>',
+    '(function() {',
+    '  "use strict";',
+    '  bw.loadDefaultStyles();'
+  ];
+
+  if (opts.theme) {
+    script.push('  bw.generateTheme("bwserve", ' + JSON.stringify(
+      typeof opts.theme === 'string'
+        ? { primary: '#006666', secondary: '#333333' }
+        : opts.theme
+    ) + ');');
+  }
+
+  script.push('  var clientId = ' + JSON.stringify(clientId) + ';');
+  script.push('  var conn = bw.clientConnect("/__bw/events/" + clientId, {');
+  script.push('    actionUrl: "/__bw/action/" + clientId,');
+  script.push('    onStatus: function(s) {');
+  script.push('      if (typeof console !== "undefined") console.log("[bwserve] " + s);');
+  script.push('    }');
+  script.push('  });');
+
+  // data-bw-action click delegation
+  script.push('  document.addEventListener("click", function(e) {');
+  script.push('    var el = e.target.closest ? e.target.closest("[data-bw-action]") : null;');
+  script.push('    if (!el) return;');
+  script.push('    e.preventDefault();');
+  script.push('    var actionData = {};');
+  script.push('    if (el.getAttribute("data-bw-id")) actionData.bwId = el.getAttribute("data-bw-id");');
+  script.push('    var form = el.closest("div") || document;');
+  script.push('    var inp = form.querySelector("input[type=text],input:not([type])");');
+  script.push('    if (inp) { actionData.inputValue = inp.value; inp.value = ""; }');
+  script.push('    conn.sendAction(el.getAttribute("data-bw-action"), actionData);');
+  script.push('  });');
+
+  // Enter key on inputs
+  script.push('  document.addEventListener("keydown", function(e) {');
+  script.push('    if (e.key === "Enter" && e.target.tagName === "INPUT") {');
+  script.push('      var form = e.target.closest("div") || document;');
+  script.push('      var btn = form.querySelector("[data-bw-action]");');
+  script.push('      if (btn) {');
+  script.push('        conn.sendAction(btn.getAttribute("data-bw-action"), { inputValue: e.target.value });');
+  script.push('        e.target.value = "";');
+  script.push('      }');
+  script.push('    }');
+  script.push('  });');
+
+  script.push('})();');
+  script.push('</script>');
+  script.push('</body>');
+  script.push('</html>');
+
+  return head.concat(script).join('\n');
+}

package/src/cli/index.js

@@ -1,21 +1,27 @@
 /**
- * Bitwrench CLI - Main entry point
+ * bwcli — Main entry point for the bitwrench command-line tool
  * Arg parsing with util.parseArgs(), help, version, dispatch
+ *
+ * Subcommands:
+ *   bwcli <file> [options]       Convert a file to styled HTML
+ *   bwcli serve [dir] [options]  Start bwserve dev server
  */
 
 import { parseArgs } from 'node:util';
 import { VERSION } from '../version.js';
 import { convertFile } from './convert.js';
+import { runServe } from './serve.js';
 
 const USAGE = `
-bitwrench v${VERSION} — Document converter & static site generator
+bwcli v${VERSION} — bitwrench command-line tool
 
 Usage:
-  bitwrench <file> [options]       Convert a file to styled HTML
-  bitwrench --version              Print version
-  bitwrench --help                 Print this help
+  bwcli <file> [options]       Convert a file to styled HTML
+  bwcli serve [dir] [options]  Start bwserve development server
+  bwcli --version              Print version
+  bwcli --help                 Print this help
 
-Options:
+Convert options:
   -o, --output <file>    Output file path (default: input with .html extension)
   -c, --css <file>       Include external CSS file
   -t, --theme <name>     Theme preset (ocean, sunset, forest, slate) or hex colors ("#pri,#sec")
@@ -26,16 +32,26 @@ Options:
   -f, --favicon <path>   Favicon path or URL
       --highlight        Include highlight.js for syntax highlighting
   -v, --verbose          Verbose output
+
+Serve options:
+  -p, --port <number>    Port to listen on (default: 7902)
+  -t, --theme <name>     Theme preset or hex colors
+      --open             Open browser on start
+  -v, --verbose          Verbose output
+
+General:
   -h, --help             Print this help
       --version          Print version
 
 Examples:
-  bitwrench README.md                          Convert README.md to README.html
-  bitwrench README.md -o index.html            Specify output file
-  bitwrench README.md -o out.html --theme ocean  Apply ocean theme
-  bitwrench README.md -o out.html --standalone   Self-contained offline HTML
-  bitwrench README.md -o out.html --highlight    With syntax highlighting
-  bitwrench doc.md --theme "#336699,#cc6633"     Custom theme colors
+  bwcli README.md                          Convert README.md to README.html
+  bwcli README.md -o index.html            Specify output file
+  bwcli README.md -o out.html --theme ocean  Apply ocean theme
+  bwcli README.md -o out.html --standalone   Self-contained offline HTML
+  bwcli README.md -o out.html --highlight    With syntax highlighting
+  bwcli doc.md --theme "#336699,#cc6633"     Custom theme colors
+  bwcli serve                              Serve current directory on port 7902
+  bwcli serve ./site --port 8080           Serve ./site on port 8080
 `.trim();
 
 /**
@@ -43,6 +59,11 @@ Examples:
  * @param {string[]} argv - process.argv.slice(2)
  */
 export function run(argv) {
+    // Check for subcommand before parseArgs (subcommands have different options)
+    if (argv.length > 0 && argv[0] === 'serve') {
+        return runServe(argv.slice(1));
+    }
+
     let values, positionals;
 
     try {
@@ -69,13 +90,13 @@ export function run(argv) {
         positionals = result.positionals;
     } catch (err) {
         console.error(`Error: ${err.message}`);
-        console.error('Run "bitwrench --help" for usage.');
+        console.error('Run "bwcli --help" for usage.');
         process.exit(1);
     }
 
     // --version
     if (values.version) {
-        console.log(`bitwrench v${VERSION}`);
+        console.log(`bwcli v${VERSION}`);
         return;
     }
 
@@ -88,7 +109,7 @@ export function run(argv) {
     // No positional args → error
     if (positionals.length === 0) {
         console.error('Error: No input file specified.');
-        console.error('Run "bitwrench --help" for usage.');
+        console.error('Run "bwcli --help" for usage.');
         process.exit(1);
     }