zback 1.3.1 → 1.4.0

package/README.md

@@ -7,11 +7,13 @@ ZBack is an opt-in remote administration agent for systems you own or are author
 ## Install and start
 
 ```sh
-npm install -g zback@1.2.1
+npm install -g zback@1.2.2
 zback
 ```
 
-On the first run, ZBack explains the remote-shell capability and asks for authorization once. It stores that decision locally, then creates a private agent credential. There are no prompts for each command.
+On the first run, ZBack presents a [Y]/[N] shell authorization question once. It stores that decision locally, then creates a private agent credential. There are no prompts for each command.
+
+Terminal status markers are colored on supported interactive terminals: yellow `[+]` for progress, red `[×]` for errors and gray `>` for contextual hints. Plain text is used when output is redirected. The command history updates as commands complete and shows each command's exit code and cumulative successes/errors. Connection problems are summarized once per incident while reconnect attempts continue automatically.
 
 The default server is `wss://zb.soymaycol.icu/ws`. To use your own backend:
 
@@ -31,7 +33,7 @@ The client requires **backend 1.2.0 or later**. The client rejects older servers
 
 | Command | Behavior |
 | --- | --- |
-| `zback` | Keep the agent in the foreground; display the session ID, MCP endpoint and live activity |
+| `zback` | Keep the agent in the foreground; display the session ID, MCP endpoint, colored connection notices, and command execution history |
 | `zback --background` | Explicitly start a detached agent |
 | `zback --status` | Show connection status, process ID and private session ID |
 | `zback --logs` | Display recent connection and command activity |

package/bin/zback.js

@@ -6,10 +6,11 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { connectAgent, execute } from '../src/agent.js';
+import { createTerminal, createEventReporter } from '../src/terminal.js';
 import { activeSession, agentKey, consentFile, hasConsent, initStateDir, logFile, readJson, resetKey, sameSession, saveJson, settingsFile, stateFile, alive } from '../src/runtime.js';
 
 const ENTRY = fileURLToPath(import.meta.url);
-const VERSION = '1.2.1';
+const VERSION = '1.2.2';
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
 
 function help() {
@@ -70,17 +71,17 @@ export function parseArgs(args) {
   return { ...options, action };
 }
 
-async function confirmOnce() {
+async function confirmOnce(terminal) {
   if (hasConsent()) return true;
   if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires an interactive terminal');
-  console.log('This module grants remote shell access to anyone holding your private session ID.');
-  console.log('Commands run with your user permissions. Keep the session ID private.');
+  terminal.question();
   const rl = createInterface({ input: stdin, output: stdout });
   try {
-    const answer = await rl.question('Do you allow remote access to your shell? This is asked only once. [y/N] ');
-    if (!['y', 'yes'].includes(answer.trim().toLowerCase())) return false;
-    saveJson(consentFile, { approved: true, at: new Date().toISOString() });
-    return true;
+    const answer = await rl.question('Your choice [y/N]: ');
+    const approved = ['y', 'yes'].includes(answer.trim().toLowerCase());
+    if (approved) saveJson(consentFile, { approved: true, at: new Date().toISOString() });
+    terminal.consent(approved);
+    return approved;
   } finally { rl.close(); }
 }
 
@@ -91,14 +92,23 @@ async function worker() {
   const started = process.env.ZBACK_WORKER_NONCE;
   if (!started) throw new Error('Worker must be launched through zback');
   const key = agentKey();
+  const terminal = createTerminal();
+  const reporter = createEventReporter(terminal);
+  let lastId = null;
   const mark = data => {
     const previous = readJson(stateFile);
     if (previous && previous.status !== 'stopped' && previous.pid !== process.pid && alive(previous.pid)) return;
     saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...data });
+    if (data.status === 'connected') {
+      reporter.clearProblem();
+      if (!lastId) terminal.connected(data.id, mcpEndpoint(settings.url));
+      else terminal.restored();
+      lastId = data.id;
+    }
   };
   mark({ status: 'connecting', id: null });
-  try { await connectAgent(settings, mark, key); }
-  finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null }); }
+  try { await connectAgent(settings, mark, key, reporter.event); }
+  finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: lastId }); }
 }
 
 function mcpEndpoint(url) {
@@ -165,43 +175,43 @@ async function follow() {
 }
 
 async function start(options) {
+  const terminal = createTerminal();
   const existing = activeSession();
   if (existing) {
     if (existing.version !== VERSION) {
-      console.error('An older ZBack agent is still running. Run zback --stop, then zback to start this version.');
+      terminal.error('An older ZBack agent is still running. Run zback --stop before starting this version.');
       process.exitCode = 1;
       return;
     }
-    console.log(`Agent already running (${existing.status}, PID ${existing.pid}).`);
-    if (existing.id) showConnection(existing.id, readJson(settingsFile)?.url || DEFAULT_URL);
+    terminal.section('+', `Agent already running (${existing.status}, PID ${existing.pid}).`);
+    if (existing.id) terminal.connected(existing.id, mcpEndpoint(readJson(settingsFile)?.url || DEFAULT_URL));
     if (!options.background) await follow();
     return;
   }
-  if (!(await confirmOnce())) { console.log('Authorization declined'); return; }
+  if (!(await confirmOnce(terminal))) return;
   initStateDir();
   const key = agentKey();
   saveJson(settingsFile, { url: options.url, cwd: options.cwd, timeout: options.timeout, maxOutput: options.maxOutput, reconnect: options.reconnect });
+  terminal.connecting();
   if (!options.background) {
     const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
     let lastId = null;
-    let previousStatus = null;
+    const reporter = createEventReporter(terminal);
     const mark = data => {
       saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...data });
       if (data.status === 'connected') {
-        if (data.id !== lastId) {
-          console.log('Connected.');
-          showConnection(data.id, options.url);
-          console.log('Monitoring requests and connection errors. Press Ctrl+C to disconnect.');
-          lastId = data.id;
-        } else if (previousStatus !== 'connected') console.log('Connection restored.');
-      } else if (data.status === 'reconnecting' && previousStatus !== 'reconnecting') console.error('Connection lost. Attempting to reconnect...');
-      else if (data.status === 'stopped' && previousStatus !== 'stopped' && lastId) console.log('Disconnected.');
-      previousStatus = data.status;
+        reporter.clearProblem();
+        if (!lastId) terminal.connected(data.id, mcpEndpoint(options.url));
+        else terminal.restored();
+        lastId = data.id;
+      }
     };
-    console.log(`Connecting to ${options.url}...`);
     mark({ status: 'connecting', id: null });
-    try { await connectAgent(options, mark, key); }
-    finally { if (sameSession(process.pid, started)) saveJson(stateFile, { pid: process.pid, started, version: VERSION, status: 'stopped', id: lastId, updated: new Date().toISOString() }); }
+    try { await connectAgent(options, mark, key, reporter.event); }
+    finally {
+      if (sameSession(process.pid, started)) saveJson(stateFile, { pid: process.pid, started, version: VERSION, status: 'stopped', id: lastId, updated: new Date().toISOString() });
+      terminal.stopped();
+    }
     return;
   }
   const fd = openSync(logFile, 'a', 0o600);
@@ -221,14 +231,13 @@ async function start(options) {
     await new Promise(resolve => setTimeout(resolve, 100));
     const state = readJson(stateFile);
     if (state?.pid === child.pid && state.started === started && state.status === 'connected' && state.id) {
-      showConnection(state.id, options.url);
+      terminal.connected(state.id, mcpEndpoint(options.url));
       connected = true;
       break;
     }
-    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) throw new Error(`Agent exited unexpectedly. Inspect logs with zback --logs`);
+    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) throw new Error('Agent exited unexpectedly. Inspect logs with zback --logs');
   }
-  if (!connected) console.log(`Agent started (PID ${child.pid}). Waiting for backend; run zback --status to inspect.`);
-  if (!options.background) await follow();
+  if (!connected) terminal.hint(`Agent started (PID ${child.pid}). Run zback --status to inspect the connection.`);
 }
 
 function stop() {
@@ -256,7 +265,7 @@ export async function main(args = process.argv.slice(2)) {
     if (options.action === 'follow') { showStatus(); return follow(); }
     if (options.action === 'reset-key') return rotate();
     return await start(options);
-  } catch (error) { console.error(`ZBack error: ${error.message}`); process.exitCode = 1; }
+  } catch (error) { createTerminal().error(error.message); process.exitCode = 1; }
 }
 
 if (process.argv[1] && realpathSync(process.argv[1]) === ENTRY) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zback",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Opt-in foreground remote shell administration with a persistent WebSocket agent and private session credential",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -2,7 +2,6 @@ import { spawn } from 'node:child_process';
 
 const children = new Set();
 const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
-const log = message => console.log(`[${new Date().toISOString()}] ${message}`);
 
 function killTree(child) {
   if (!child?.pid) return;
@@ -54,7 +53,7 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
   });
 }
 
-export async function connectAgent(options, onState, token) {
+export async function connectAgent(options, onState, token, onEvent = () => {}) {
   let stopped = false;
   let retries = 0;
   let socket;
@@ -62,6 +61,7 @@ export async function connectAgent(options, onState, token) {
   let lastId = null;
   let lastError = null;
   const update = (status, data = {}) => onState({ status, ...data });
+  const emit = event => { try { onEvent(event); } catch { /* UI failures must not interrupt command execution. */ } };
   const shutdown = () => {
     stopped = true;
     if (cancelDelay) cancelDelay();
@@ -92,7 +92,7 @@ export async function connectAgent(options, onState, token) {
           const messageListener = event => {
             let message;
             try { message = JSON.parse(event.data); }
-            catch { log('Ignored invalid server message'); return; }
+            catch { emit({ type: 'protocol-warning', problem: 'Received an invalid server message' }); return; }
             if (message.type === 'welcome') {
               if (welcomed) return;
               if (message.protocolVersion !== 2 || typeof message.id !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.id)) {
@@ -103,6 +103,14 @@ export async function connectAgent(options, onState, token) {
                 reject(mismatch);
                 return;
               }
+              if (lastId && message.id !== lastId) {
+                clearTimeout(timer);
+                current.close(1000, 'Session identifier changed');
+                const mismatch = new Error('The server returned a different session identifier after reconnecting');
+                mismatch.code = 'SESSION_MISMATCH';
+                reject(mismatch);
+                return;
+              }
               welcomed = true;
               clearTimeout(timer);
               retries = 0;
@@ -117,23 +125,22 @@ export async function connectAgent(options, onState, token) {
               const command = message.command;
               if (typeof command !== 'string' || !command.trim() || command.length > 4096 || command.includes('\0')) return;
               const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) && message.timeoutMs > 0 ? message.timeoutMs : options.timeout);
-              log(`Running authorized request ${message.requestId}`);
               const result = await execute(command, options.cwd, timeout, options.maxOutput);
-              log(`Request ${message.requestId}: ${result.timedOut ? 'timed out' : result.ok ? 'completed' : 'failed'}`);
+              emit({ type: 'command-result', command, result });
               if (current.readyState === WebSocket.OPEN && !stopped) current.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
-            }).catch(error => log(`Request processing error: ${error.message}`));
+            }).catch(error => emit({ type: 'agent-error', problem: `Request processing failed: ${error.message}` }));
           };
           current.addEventListener('message', messageListener);
           current.addEventListener('close', event => {
             clearTimeout(timer);
             if (!welcomed) reject(new Error(`Backend rejected connection (WebSocket ${event.code}: ${event.reason || 'no reason'})`));
-            else { if (!stopped) log(`Connection closed (${event.code}: ${event.reason || 'connection lost'})`); resolve(); }
+            else { if (!stopped) emit({ type: 'connection-lost', problem: 'Connection lost' }); resolve(); }
           }, { once: true });
           current.addEventListener('error', () => { if (!welcomed) { clearTimeout(timer); reject(new Error('WebSocket connection failed')); } }, { once: true });
         });
       } catch (error) {
-        if (!stopped && error.code === 'INCOMPATIBLE_BACKEND') throw error;
-        if (!stopped && error.message !== lastError) { log(`Connection error: ${error.message}`); lastError = error.message; }
+        if (!stopped && ['INCOMPATIBLE_BACKEND', 'SESSION_MISMATCH'].includes(error.code)) throw error;
+        if (!stopped && error.message !== lastError) { emit({ type: 'connection-error', problem: error.message }); lastError = error.message; }
       }
       killRunningCommands();
       if (stopped || !options.reconnect) break;

package/src/terminal.js

@@ -0,0 +1,98 @@
+const ANSI = Object.freeze({ yellow: '\x1b[33m', red: '\x1b[31m', gray: '\x1b[90m', white: '\x1b[37m', reset: '\x1b[0m' });
+
+// Never allow server-supplied text to inject terminal control sequences.
+export function terminalText(value, maxLength = 240) {
+  const text = String(value ?? 'unknown')
+    .replace(/\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\)?)/g, '')
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}
+
+export function createTerminal({ output = process.stdout, color = Boolean(output.isTTY && !process.env.NO_COLOR) } = {}) {
+  const tint = (s, name) => color ? `${ANSI[name]}${s}${ANSI.reset}` : s;
+  const write = line => output.write(`${line}\n`);
+  const section = (symbol, text, tone = 'yellow') => write(`${tint(`[${symbol}]`, tone)} ${tint(text, 'white')}`);
+  const detail = line => write(`${tint(' -', 'gray')} ${tint(line, 'white')}`);
+  const hint = line => write(`${tint('>', 'gray')} ${tint(line, 'gray')}`);
+  const gap = () => write('');
+
+  return {
+    section, detail, hint, gap,
+    question() {
+      section('?', 'Shell access authorization');
+      write(tint('Do you allow ZBack to provide remote shell access to holders of your private session ID?', 'white'));
+      write(`${tint('[Y]', 'yellow')} ${tint('Yes, I accept', 'white')}  ${tint('[N]', 'yellow')} ${tint('No, I do not accept', 'white')}`);
+      hint('Your decision is saved. Individual commands will not trigger additional prompts.');
+    },
+    consent(approved) {
+      hint(approved ? 'Selected: Yes. Remote shell access is authorized.' : 'Selected: No. Remote shell access remains disabled.');
+      gap();
+    },
+    connecting() {
+      section('+', 'Connecting to the server, hang on a minute.');
+      hint('This may take a moment depending on your internet connection.');
+      gap();
+    },
+    connected(id, endpoint) {
+      section('+', 'Setting up our environment');
+      detail(`Session Identifier: "${terminalText(id, 90)}"`);
+      detail(`MCP Server: "${terminalText(endpoint, 512)}"`);
+      detail('MCP Tools: "zback_status", "zback_execute"');
+      hint('Enjoy being able to have a model manage your environment. Keep your ID private.');
+      gap();
+    },
+    restored() {
+      section('+', 'Connection restored.');
+      hint('Your session identifier has not changed.');
+      gap();
+    },
+    error(problem, retrying = false) {
+      section('×', 'Oops, an error has occurred.', 'red');
+      detail(`Problem: "${terminalText(problem, 240)}"`);
+      hint(retrying ? 'This error is being handled. Reconnecting automatically, please wait.' : 'The connection cannot continue. Check the problem above.');
+      gap();
+    },
+    stopped() {
+      section('+', 'Disconnected.');
+    },
+    command(result, totals) {
+      if (totals.count === 1) section('+', 'History of executed commands');
+      const code = Number.isInteger(result.code) ? result.code : result.timedOut ? 'timeout' : 'unknown';
+      detail(`${JSON.stringify(terminalText(result.command))} was executed with exit code ${code}.`);
+      const countWord = totals.count === 1 ? 'command was' : 'commands were';
+      const errorWord = totals.errors === 1 ? 'an error' : 'errors';
+      hint(`Currently, ${totals.count} ${countWord} executed, ${totals.errors} with ${errorWord} and ${totals.successes} successfully.`);
+    }
+  };
+}
+
+export function createCommandTracker(terminal) {
+  const totals = { count: 0, successes: 0, errors: 0 };
+  return event => {
+    if (event.type !== 'command-result') return;
+    totals.count++;
+    if (event.result.ok) totals.successes++;
+    else totals.errors++;
+    terminal.command({ command: event.command, ...event.result }, totals);
+  };
+}
+
+export function createEventReporter(terminal) {
+  const reportCommand = createCommandTracker(terminal);
+  let activeProblem = null;
+  return {
+    clearProblem() { activeProblem = null; },
+    event(event) {
+      if (event.type === 'command-result') return reportCommand(event);
+      if (event.type === 'connection-lost' || event.type === 'connection-error') {
+        // A dropped connection may lead to many retries; report the incident once.
+        if (activeProblem !== null) return;
+        activeProblem = event.problem;
+        return terminal.error(event.problem, true);
+      }
+      if (event.type === 'agent-error' || event.type === 'protocol-warning') terminal.error(event.problem, false);
+    }
+  };
+}