bitwrench 2.0.18 → 2.0.20

package/src/cli/attach.js

@@ -70,6 +70,14 @@ Examples:
   bw> /screenshot body page.png
   bw> /listen .bw-btn click
   bw> /mount #app card {"title":"Hello","content":"World"}
+
+  Workflow — build a dashboard from your terminal:
+  bw> /render #app {"t":"div","c":[{"t":"h2","c":"Dashboard"},{"t":"div","a":{"id":"stats"},"c":[{"t":"span","a":{"id":"users"},"c":"Users: 0"},{"t":"span","a":{"id":"orders"},"c":"Orders: 0"}]}]}
+  bw> /patch users "Users: 342"
+  bw> /patch orders "Orders: 28"
+  bw> /mount #app card {"title":"Status","content":"All systems go"}
+  bw> /tree #app 2
+  bw> /listen .bw-btn click
 `.trim();
 
 /**
@@ -91,8 +99,9 @@ export function wrapExpression(code) {
 /**
  * Run the attach subcommand.
  * @param {string[]} argv - arguments after "attach"
+ * @param {object} [ioOpts] - optional input/output streams for testing
  */
-export function runAttach(argv) {
+export function runAttach(argv, ioOpts) {
   var values;
 
   try {
@@ -129,19 +138,25 @@ export function runAttach(argv) {
   }
 
   // Dynamic import of bwserve
-  import('../bwserve/index.js').then(function(bwserve) {
-    startAttach(bwserve, { port, allowScreenshot, verbose });
+  var io = ioOpts || {};
+  var importPath = io._importPath || '../bwserve/index.js';
+  var importPromise = import(importPath).then(function(bwserve) {
+    return startAttach(bwserve, { port: port, allowScreenshot: allowScreenshot, verbose: verbose, input: io.input, output: io.output });
   }).catch(function(err) {
     console.error('Failed to load bwserve: ' + err.message);
     process.exit(1);
   });
+
+  return importPromise;
 }
 
 /**
  * Start the attach server and REPL.
- * @private
+ * @param {object} bwserve - The bwserve module (or mock)
+ * @param {object} opts - { port, allowScreenshot, verbose, input }
+ * @returns {{ rl: object, app: object }} readline interface and app for testing
  */
-function startAttach(bwserve, opts) {
+export function startAttach(bwserve, opts) {
   var app = bwserve.create({
     port: opts.port,
     title: 'bwcli attach',
@@ -180,7 +195,7 @@ function startAttach(bwserve, opts) {
       // Print connection message
       process.stdout.write('\r\x1b[K');
       console.log('[connected] client ' + clientId);
-      rl.prompt(true);
+      safePrompt(true);
 
       // Listen for events from _bw_listen
       client.on('_bw_event', function(data) {
@@ -188,7 +203,7 @@ function startAttach(bwserve, opts) {
         console.log('[event] ' + data.event + ' on ' + data.selector +
           ' \u2192 ' + data.tagName + (data.id ? '#' + data.id : '') +
           (data.text ? ' "' + data.text.slice(0, 50) + '"' : ''));
-        rl.prompt(true);
+        safePrompt(true);
       });
 
       // Handle disconnect
@@ -205,7 +220,7 @@ function startAttach(bwserve, opts) {
         } else {
           console.log('Waiting for connection...');
         }
-        rl.prompt(true);
+        safePrompt(true);
       });
     }
   };
@@ -223,20 +238,25 @@ function startAttach(bwserve, opts) {
     console.log('Waiting for connection...');
     console.log('Type /help for commands, /quit to exit.');
     console.log('');
-    rl.prompt();
+    safePrompt();
   });
 
   // Create readline REPL
   var rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
+    input: opts.input || process.stdin,
+    output: opts.output || process.stdout,
     prompt: 'bw> '
   });
+  var rlClosed = false;
+
+  function safePrompt(preserveCursor) {
+    if (!rlClosed) rl.prompt(preserveCursor);
+  }
 
   rl.on('line', function(line) {
     line = line.trim();
     if (!line) {
-      rl.prompt();
+      safePrompt();
       return;
     }
 
@@ -249,7 +269,7 @@ function startAttach(bwserve, opts) {
     // JS expression — requires active client
     if (!activeClient) {
       console.log('No client connected. Add the attach script to a page first.');
-      rl.prompt();
+      safePrompt();
       return;
     }
 
@@ -268,26 +288,33 @@ function startAttach(bwserve, opts) {
       } else {
         console.log('undefined');
       }
-      rl.prompt();
+      safePrompt();
     }).catch(function(err) {
       console.error('[error] ' + err.message);
-      rl.prompt();
+      safePrompt();
     });
   });
 
   rl.on('close', function() {
+    rlClosed = true;
     console.log('\nExiting.');
     app.close().then(function() {
       process.exit(0);
     });
   });
+
+  return { rl: rl, app: app };
 }
 
 /**
  * Handle slash commands in the REPL.
- * @private
+ * @param {string} line - The full command line (e.g., "/tree #app 2")
+ * @param {object|null} activeClient - The active BwServeClient, or null
+ * @param {Map} clients - Map of clientId -> client
+ * @param {object} opts - { allowScreenshot, verbose }
+ * @param {object} rl - readline interface with prompt() method
  */
-function handleSlashCommand(line, activeClient, clients, opts, rl) {
+export function handleSlashCommand(line, activeClient, clients, opts, rl) {
   var parts = line.split(/\s+/);
   var cmd = parts[0].toLowerCase();
 
@@ -505,9 +532,10 @@ function handleSlashCommand(line, activeClient, clients, opts, rl) {
 
 /**
  * Pretty-print a DOM tree from _bw_tree.
- * @private
+ * @param {object} node - Tree node with tag, id, cls, children
+ * @param {number} indent - Current indentation level
  */
-function printTree(node, indent) {
+export function printTree(node, indent) {
   if (!node) return;
   var prefix = '  '.repeat(indent);
   var label = node.tag || '?';
@@ -523,9 +551,8 @@ function printTree(node, indent) {
 
 /**
  * Print the REPL help reference.
- * @private
  */
-function printHelp() {
+export function printHelp() {
   console.log([
     '',
     'bwcli attach — REPL Commands',
@@ -550,6 +577,11 @@ function printHelp() {
     '  /unlisten <sel> <event>    Remove a listener',
     '  /exec <code>               Execute JS without capturing return value',
     '  /clients                   List connected clients',
+    '',
+    '  Workflow — build and push a component:',
+    '    /render #app {"t":"div","c":[{"t":"h2","c":"Hello"},{"t":"span","a":{"id":"msg"},"c":"..."}]}',
+    '    /patch msg "Component pushed!"',
+    '    /mount #app card {"title":"Status","content":"OK"}',
     ''
   ].join('\n'));
 }

package/src/cli/serve.js

@@ -5,6 +5,10 @@
  * via an input HTTP port or stdin. Broadcasts messages to all connected
  * browser tabs.
  *
+ * The input HTTP port also supports interactive commands: POST a JSON
+ * object with a `command` field and receive the result as the HTTP
+ * response. This is the programmatic equivalent of bwcli attach's REPL.
+ *
  * Usage:
  *   bwcli serve [dir] [--port N] [--listen N] [--stdin] [--theme name]
  */
@@ -40,6 +44,8 @@ Examples:
   bwcli serve --stdin                     Read from pipe instead of input port
   sensor-reader | bwcli serve --stdin     Pipe sensor data to browser
   curl -X POST :9000 -d '{"type":"replace","target":"#app","node":{"t":"h1","c":"Hi"}}'
+  curl -X POST :9000 -d '{"command":"query","code":"document.title"}'
+  curl -X POST :9000 -d '{"command":"clients"}'
 `.trim();
 
 /**
@@ -131,11 +137,151 @@ function parseRelaxedJSON(str) {
     return JSON.parse(out.join(''));
 }
 
+// Required fields per command (async commands also listed)
+var _COMMAND_REQUIRED = {
+    query:    ['code'],
+    screenshot: [],
+    tree:     [],
+    mount:    ['selector', 'factory'],
+    exec:     ['code'],
+    render:   ['selector', 'taco'],
+    patch:    ['id'],
+    listen:   ['selector', 'event'],
+    unlisten: ['selector', 'event'],
+    clients:  []
+};
+
+// Commands that return a result via promise
+var _ASYNC_COMMANDS = { query: 1, screenshot: 1, tree: 1, mount: 1 };
+
+/**
+ * Handle an interactive command from the listen port.
+ *
+ * @param {Object} msg - Parsed message with `command` field
+ * @param {Object} app - BwServeApp instance (has _clients Map)
+ * @param {boolean} verbose - Log details to stderr
+ * @returns {Promise<Object>} Response object ({ok, result, clientId} or {error})
+ */
+function handleCommand(msg, app, verbose) {
+    var cmd = msg.command;
+
+    // clients: no client needed
+    if (cmd === 'clients') {
+        var ids = [];
+        for (var entry of app._clients) {
+            if (entry[1] && entry[1].client) ids.push(entry[0]);
+        }
+        return Promise.resolve({ ok: true, clients: ids });
+    }
+
+    // Validate command name
+    if (!_COMMAND_REQUIRED.hasOwnProperty(cmd)) {
+        return Promise.resolve({ error: 'Unknown command: ' + cmd });
+    }
+
+    // Validate required fields
+    var required = _COMMAND_REQUIRED[cmd];
+    for (var k = 0; k < required.length; k++) {
+        if (msg[required[k]] === undefined) {
+            return Promise.resolve({ error: 'Missing required field: ' + required[k] });
+        }
+    }
+
+    // Select client
+    var client = null;
+    var clientId = null;
+
+    if (msg.clientId) {
+        var record = app._clients.get(msg.clientId);
+        if (record && record.client) {
+            client = record.client;
+            clientId = msg.clientId;
+        } else {
+            return Promise.resolve({ error: 'Client not found: ' + msg.clientId });
+        }
+    } else {
+        // Pick first connected client
+        for (var pair of app._clients) {
+            if (pair[1] && pair[1].client && !pair[1].client._closed) {
+                client = pair[1].client;
+                clientId = pair[0];
+                break;
+            }
+        }
+    }
+
+    if (!client) {
+        return Promise.resolve({ error: 'No clients connected' });
+    }
+
+    var timeout = msg.timeout;
+
+    if (verbose) {
+        console.error('[command] ' + cmd + ' -> client ' + clientId);
+    }
+
+    // Dispatch
+    try {
+        switch (cmd) {
+            case 'query':
+                return client.query(msg.code, { timeout: timeout || 5000 }).then(function(result) {
+                    return { ok: true, result: result, clientId: clientId };
+                });
+
+            case 'screenshot':
+                return client.screenshot(msg.selector || 'body', { timeout: timeout || 10000 }).then(function(result) {
+                    // Convert Buffer to base64 for JSON response
+                    var data = result && result.data ? result.data.toString('base64') : null;
+                    return { ok: true, result: { data: data, width: result.width, height: result.height, format: result.format }, clientId: clientId };
+                });
+
+            case 'tree':
+                var pend = client._pend(timeout || 10000);
+                client.call('_bw_tree', {
+                    selector: msg.selector || 'body',
+                    depth: msg.depth || 3,
+                    requestId: pend.requestId
+                });
+                return pend.promise.then(function(result) {
+                    return { ok: true, result: result, clientId: clientId };
+                });
+
+            case 'mount':
+                return client.mount(msg.selector, msg.factory, msg.props || {}, { timeout: timeout || 10000 }).then(function(result) {
+                    return { ok: true, result: result, clientId: clientId };
+                });
+
+            case 'exec':
+                client.exec(msg.code);
+                return Promise.resolve({ ok: true, clientId: clientId });
+
+            case 'render':
+                client.render(msg.selector, msg.taco);
+                return Promise.resolve({ ok: true, clientId: clientId });
+
+            case 'patch':
+                client.patch(msg.id, msg.content, msg.attr);
+                return Promise.resolve({ ok: true, clientId: clientId });
+
+            case 'listen':
+                client.call('_bw_listen', { selector: msg.selector, event: msg.event });
+                return Promise.resolve({ ok: true, clientId: clientId });
+
+            case 'unlisten':
+                client.call('_bw_unlisten', { selector: msg.selector, event: msg.event });
+                return Promise.resolve({ ok: true, clientId: clientId });
+        }
+    } catch (err) {
+        return Promise.resolve({ error: err.message });
+    }
+}
+
 /**
  * Run the serve subcommand.
  * @param {string[]} argv - arguments after "serve"
+ * @param {object} [ioOpts] - optional overrides for testing
  */
-export function runServe(argv) {
+export function runServe(argv, ioOpts) {
     var values, positionals;
 
     try {
@@ -186,7 +332,9 @@ export function runServe(argv) {
     }
 
     // Dynamic import of bwserve to avoid loading it at parse time
-    import('../../src/bwserve/index.js').then(function(bwserve) {
+    var io = ioOpts || {};
+    var importPath = io._importPath || '../../src/bwserve/index.js';
+    var importPromise = import(importPath).then(function(bwserve) {
         startServer(bwserve, {
             dir: dir,
             webPort: webPort,
@@ -202,6 +350,8 @@ export function runServe(argv) {
         console.error('Failed to load bwserve: ' + err.message);
         process.exit(1);
     });
+
+    return importPromise;
 }
 
 /**
@@ -257,7 +407,11 @@ function startServer(bwserve, opts) {
 }
 
 /**
- * Start the input HTTP server for receiving protocol messages.
+ * Start the input HTTP server for receiving protocol messages and interactive commands.
+ *
+ * Messages with a `command` field are treated as interactive commands --
+ * routed to a specific client and the result returned in the HTTP response.
+ * Messages with a `type` field (no `command`) are broadcast to all clients.
  */
 function startInputServer(app, listenPort, verbose) {
     var inputServer = createServer(function(req, res) {
@@ -277,6 +431,25 @@ function startInputServer(app, listenPort, verbose) {
                 return;
             }
 
+            // Interactive command path
+            if (msg.command) {
+                handleCommand(msg, app, verbose).then(function(result) {
+                    var status = result.error ? 400 : 200;
+                    // Unknown command and client-not-found get 400; timeout also 400
+                    res.writeHead(status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(result));
+                }).catch(function(err) {
+                    var errMsg = err && err.message ? err.message : String(err);
+                    if (verbose) {
+                        console.error('[command] error: ' + errMsg);
+                    }
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: errMsg }));
+                });
+                return;
+            }
+
+            // Broadcast path (existing behavior)
             var count = app.broadcast(msg);
             if (verbose) {
                 console.error('[input] ' + msg.type + ' -> ' + count + ' client(s)');
@@ -327,3 +500,6 @@ function startStdinReader(app, verbose) {
         if (verbose) console.error('[stdin] Input stream closed. Server stays running.');
     });
 }
+
+// Export private functions for testability
+export { parseMessage, parseRelaxedJSON, startServer, startInputServer, startStdinReader, handleCommand };

package/src/version.js

@@ -3,14 +3,14 @@
  * DO NOT EDIT DIRECTLY - Use npm run generate-version
  */
 
-export const VERSION = '2.0.18';
+export const VERSION = '2.0.20';
 export const VERSION_INFO = {
-  version: '2.0.18',
+  version: '2.0.20',
   name: 'bitwrench',
   description: 'A library for javascript UI functions.',
   license: 'BSD-2-Clause',
   homepage: 'https://deftio.github.com/bitwrench/pages',
   repository: 'git+https://github.com/deftio/bitwrench.git',
   author: 'manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)',
-  buildDate: '2026-03-17T00:50:09.505Z'
+  buildDate: '2026-03-23T05:19:31.951Z'
 };