bmweb-cli 0.1.6 → 0.1.7

package/dist/bmweb.js

@@ -81,8 +81,866 @@ function helpLines(spec) {
   return rows.map(([l, h]) => `  ${l.padEnd(w)}  ${h}`.trimEnd());
 }
 
+// src/serial.ts
+import { readdirSync } from "node:fs";
+var RX_KICK_MS = 4;
+var PORT_PATTERNS = [
+  /^cu\.usbserial/i,
+  /^cu\.SLAB/i,
+  /^cu\.wchusbserial/i,
+  /^ttyUSB/i,
+  /^ttyACM/i
+];
+var NodeSerialPort = class {
+  path;
+  opener;
+  binding = null;
+  /** chunks heard and not yet read */
+  chunks = [];
+  /** reads waiting for bytes, oldest first, when the queue is empty */
+  waiters = [];
+  /** the receive kick, running while a read waits (see startKick) */
+  kick = null;
+  /** a kick ioctl in flight, so they never pile up */
+  kicking = false;
+  /** the lines as last set, so a partial setSignals keeps the others */
+  lines = { dtr: false, rts: false, brk: false };
+  /** the wire trace sink, when the CLI wants one */
+  info;
+  /**
+   * @param path - the device path
+   * @param opener - how a binding is opened
+   * @param info - vendor and product ids, when known (portLabel shows them)
+   */
+  constructor(path, opener, info = {}) {
+    this.path = path;
+    this.opener = opener;
+    this.info = info;
+  }
+  /** Is a binding open (Web Serial's SerialPort.connected). */
+  get connected() {
+    return !!this.binding;
+  }
+  /**
+   * Open the device with the given settings.
+   * @param cfg - baud, bits, parity
+   */
+  async open(cfg) {
+    if (this.binding) throw new Error(`${this.path} is already open`);
+    const b = await this.opener(this.path, cfg);
+    this.binding = b;
+    this.chunks = [];
+    b.onData((chunk) => this.push(chunk));
+  }
+  /**
+   * Close the device: the binding goes, a waiting read is told `done`.
+   */
+  async close() {
+    const b = this.binding;
+    this.binding = null;
+    this.stopKick();
+    this.wakeAll();
+    this.chunks = [];
+    if (b) await b.close();
+  }
+  /** Tell every waiting read the port is done, and forget them. */
+  wakeAll() {
+    const ws = this.waiters;
+    this.waiters = [];
+    for (const w of ws) w({ value: void 0, done: true });
+  }
+  /**
+   * Bytes the binding heard: to the waiting read, else queued.
+   * @param chunk - the bytes
+   */
+  push(chunk) {
+    if (!chunk.length) return;
+    const w = this.waiters.shift();
+    if (w) {
+      w({ value: chunk, done: false });
+      return;
+    }
+    this.chunks.push(chunk);
+  }
+  /** The readable side: getReader() hands back the one reader. */
+  get readable() {
+    return {
+      getReader: () => ({
+        read: () => this.read(),
+        cancel: async () => this.cancel(),
+        releaseLock: () => {
+        }
+      })
+    };
+  }
+  /** The writable side: getWriter() hands back the one writer. */
+  get writable() {
+    return {
+      getWriter: () => ({
+        write: (bytes) => this.write(bytes),
+        releaseLock: () => {
+        }
+      })
+    };
+  }
+  /**
+   * One read: the next chunk, or `done` when the port is closed.
+   * @returns the read result
+   */
+  read() {
+    const next = this.chunks.shift();
+    if (next) return Promise.resolve({ value: next, done: false });
+    if (!this.binding) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve2) => {
+      this.waiters.push(resolve2);
+      this.startKick();
+    });
+  }
+  /**
+   * Make the driver deliver what it has heard.
+   *
+   * THE BUG THIS FIXES. On macOS the built-in FTDI driver does not wake the
+   * reader when bytes arrive: with a read armed and the process simply
+   * waiting, an ECU's answer sat in the driver until some OTHER call touched
+   * the device (the next write, a modem-line change, close), and only then
+   * came out -- measured on a real car as 0 bytes for the first exchange
+   * after open and every later exchange delivering the PREVIOUS one's bytes
+   * at its start. Polling the modem lines (a TIOCMGET, no wire traffic)
+   * every few milliseconds while a read waits makes each answer arrive
+   * within the poll interval, first exchange included. The interval never
+   * holds the process open and stops itself once no read is waiting.
+   */
+  startKick() {
+    if (this.kick) return;
+    const tick = () => {
+      const b = this.binding;
+      if (!b || !this.waiters.length) {
+        this.stopKick();
+        return;
+      }
+      if (this.kicking) return;
+      this.kicking = true;
+      b.get().catch(() => null).then(() => {
+        this.kicking = false;
+      });
+    };
+    this.kick = setInterval(tick, RX_KICK_MS);
+    if (typeof this.kick === "object" && "unref" in this.kick)
+      this.kick.unref();
+  }
+  /** Stop the receive kick. */
+  stopKick() {
+    if (!this.kick) return;
+    clearInterval(this.kick);
+    this.kick = null;
+  }
+  /**
+   * Cancel the reader: a waiting read is told `done`, buffered bytes go.
+   */
+  cancel() {
+    this.chunks = [];
+    this.wakeAll();
+  }
+  /**
+   * Write bytes. Resolves when the OS has them, not when they have left the
+   * wire: the bus then holds DTR for the telegram's own byte time, and
+   * waiting for transmission here would double that hold and lose the
+   * ECU's answer (the reference interface's DtrTimeCorrCom is 0.3 ms).
+   * @param bytes - the framed request
+   */
+  async write(bytes) {
+    if (!this.binding) throw new Error(`${this.path} is not open`);
+    await this.binding.write(bytes);
+  }
+  /**
+   * Drive the modem lines. A partial call keeps the lines it does not name,
+   * as Web Serial does; the binding always gets all three, because
+   * `serialport` would otherwise assert the ones left unsaid.
+   * @param s - the lines to set
+   */
+  async setSignals(s) {
+    if (!this.binding) throw new Error(`${this.path} is not open`);
+    if (s.dataTerminalReady !== void 0)
+      this.lines.dtr = !!s.dataTerminalReady;
+    if (s.requestToSend !== void 0) this.lines.rts = !!s.requestToSend;
+    if (s.break !== void 0) this.lines.brk = !!s.break;
+    await this.binding.set({ ...this.lines });
+  }
+  /**
+   * Read the modem lines (KL15 arrives on DSR or DCD of a K+DCAN cable).
+   * @returns the lines, or null when the binding cannot say
+   */
+  async getSignals() {
+    if (!this.binding) return null;
+    const st = await this.binding.get();
+    if (!st) return null;
+    return {
+      dataSetReady: !!st.dsr,
+      dataCarrierDetect: !!st.dcd,
+      clearToSend: !!st.cts
+    };
+  }
+  /**
+   * The USB ids, for the bus's port label.
+   * @returns what is known
+   */
+  getInfo() {
+    return this.info;
+  }
+  /** Web Serial's disconnect event; a pulled USB cable is not watched here. */
+  addEventListener() {
+  }
+};
+var serialportModule = null;
+async function loadSerialport() {
+  if (serialportModule) return serialportModule;
+  try {
+    serialportModule = await import("serialport");
+  } catch {
+    throw new CliError(
+      "the serialport package is not installed; run: npm i -g serialport (or reinstall bmweb-cli with its optional dependencies)"
+    );
+  }
+  return serialportModule;
+}
+async function openSerialportBinding(path, cfg) {
+  const mod = await loadSerialport();
+  const port = new mod.SerialPort({
+    path,
+    baudRate: cfg.baudRate,
+    dataBits: cfg.dataBits,
+    stopBits: cfg.stopBits,
+    parity: cfg.parity,
+    autoOpen: false,
+    // keep the lines where we leave them across close/open
+    hupcl: false
+  });
+  await new Promise(
+    (res, rej) => port.open(
+      (e) => e ? rej(new CliError(`cannot open ${path}: ${e.message}`)) : res()
+    )
+  );
+  const call = (fn) => new Promise((res, rej) => fn((e) => e ? rej(e) : res()));
+  const binding = {
+    write: (bytes) => call((cb) => port.write(Buffer.from(bytes), cb)),
+    onData: (fn) => port.on("data", (b) => fn(new Uint8Array(b))),
+    set: (s) => call(
+      (cb) => port.set(
+        {
+          dtr: s.dtr,
+          rts: s.rts,
+          brk: s.brk,
+          cts: false,
+          dsr: false,
+          ...process.platform === "linux" ? { lowLatency: true } : {}
+        },
+        cb
+      )
+    ),
+    get: () => new Promise((res) => port.get((e, st) => res(e || !st ? null : st))),
+    close: () => new Promise((res) => port.close(() => res()))
+  };
+  await binding.set({ dtr: false, rts: false, brk: false });
+  return binding;
+}
+async function listPorts(devDir = "/dev") {
+  const found = /* @__PURE__ */ new Map();
+  try {
+    for (const name of readdirSync(devDir))
+      if (PORT_PATTERNS.some((re) => re.test(name)))
+        found.set(`${devDir}/${name}`, "");
+  } catch {
+  }
+  try {
+    const mod = await loadSerialport();
+    for (const p of await mod.SerialPort.list()) {
+      const base = p.path.split("/").pop() || p.path;
+      if (!PORT_PATTERNS.some((re) => re.test(base))) continue;
+      const detail = [
+        p.manufacturer,
+        p.vendorId && p.productId ? `${p.vendorId}:${p.productId}` : "",
+        p.serialNumber ? `sn ${p.serialNumber}` : ""
+      ].filter(Boolean).join("  ");
+      found.set(p.path, detail);
+    }
+  } catch {
+  }
+  return [...found.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([path, detail]) => ({ path, detail }));
+}
+function choosePort(wanted, candidates) {
+  if (wanted) return wanted;
+  if (candidates.length === 1) return candidates[0].path;
+  if (!candidates.length)
+    throw new CliError(
+      "no K+DCAN cable found (looked for cu.usbserial*, cu.SLAB*, cu.wchusbserial*, ttyUSB*, ttyACM*); pass --port <device>"
+    );
+  throw new CliError(
+    `several ports found; pass --port: ${candidates.map((c) => c.path).join(", ")}`
+  );
+}
+
+// src/ws.ts
+import { createHash, randomBytes } from "node:crypto";
+import { createServer, connect } from "node:net";
+var WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+var OP_CONT = 0;
+var OP_TEXT = 1;
+var OP_BINARY = 2;
+var OP_CLOSE = 8;
+var OP_PING = 9;
+var OP_PONG = 10;
+var MAX_MESSAGE = 1 << 20;
+var CLOSE_NORMAL = 1e3;
+var CLOSE_POLICY = 1008;
+var WsConnection = class {
+  socket;
+  masked;
+  handlers = {};
+  /** bytes received and not yet parsed into a frame */
+  buf = Buffer.alloc(0);
+  /** the opcode of the message being assembled across continuation frames */
+  fragOp = 0;
+  /** the fragments of that message */
+  frags = [];
+  /** how many bytes those fragments hold */
+  fragLen = 0;
+  /** has a close frame been sent, so the next one is not sent twice */
+  closing = false;
+  /** has onClose already fired */
+  closed = false;
+  /**
+   * @param socket - the open TCP socket, past the handshake
+   * @param masked - true on the client end, which must mask what it sends
+   */
+  constructor(socket, masked) {
+    this.socket = socket;
+    this.masked = masked;
+    socket.setNoDelay(true);
+    socket.on("data", (d) => this.feed(d));
+    socket.on("error", (e) => {
+      this.handlers.onError?.(e);
+      this.finish(1006, e.message);
+    });
+    socket.on("close", () => this.finish(1006, "socket closed"));
+  }
+  /**
+   * Take the handlers. Set once, right after construction, so no frame is
+   * parsed before someone is listening.
+   * @param h - the handlers
+   */
+  on(h) {
+    this.handlers = h;
+  }
+  /**
+   * Send a text frame.
+   * @param text - the payload
+   */
+  sendText(text) {
+    this.send(OP_TEXT, Buffer.from(text, "utf8"));
+  }
+  /**
+   * Send a binary frame.
+   * @param bytes - the payload
+   */
+  sendBinary(bytes) {
+    this.send(OP_BINARY, Buffer.from(bytes));
+  }
+  /**
+   * Send a close frame and end the socket.
+   * @param code - the close code
+   * @param reason - the human reason, at most 123 bytes on the wire
+   */
+  close(code = CLOSE_NORMAL, reason = "") {
+    if (this.closing) return;
+    this.closing = true;
+    const r = Buffer.from(reason, "utf8").subarray(0, 123);
+    const body = Buffer.alloc(2 + r.length);
+    body.writeUInt16BE(code, 0);
+    r.copy(body, 2);
+    try {
+      this.send(OP_CLOSE, body);
+    } catch {
+    }
+    this.socket.end();
+  }
+  /** Drop the socket without a close frame (a handshake refusal). */
+  destroy() {
+    this.closing = true;
+    this.socket.destroy();
+  }
+  /**
+   * Frame a payload and write it.
+   * @param op - the opcode
+   * @param payload - the bytes
+   */
+  send(op, payload) {
+    if (this.socket.destroyed) return;
+    this.socket.write(encodeFrame(op, payload, this.masked));
+  }
+  /**
+   * Take bytes off the socket and parse every whole frame in them.
+   * @param chunk - what arrived
+   */
+  feed(chunk) {
+    this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk;
+    for (; ; ) {
+      const frame = decodeFrame(this.buf, !this.masked);
+      if (frame === null) return;
+      if (frame instanceof Error) {
+        this.handlers.onError?.(frame);
+        this.close(1002, frame.message);
+        return;
+      }
+      this.buf = this.buf.subarray(frame.size);
+      this.handle(frame.fin, frame.op, frame.payload);
+      if (this.closed) return;
+    }
+  }
+  /**
+   * One parsed frame: control frames answered here, data frames assembled.
+   * @param fin - is this the message's last frame
+   * @param op - the opcode
+   * @param payload - the frame's bytes
+   */
+  handle(fin, op, payload) {
+    if (op === OP_PING) {
+      this.send(OP_PONG, payload);
+      return;
+    }
+    if (op === OP_PONG) return;
+    if (op === OP_CLOSE) {
+      const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005;
+      const reason = payload.length > 2 ? payload.subarray(2).toString() : "";
+      if (!this.closing) this.close(code === 1005 ? CLOSE_NORMAL : code, "");
+      this.finish(code, reason);
+      return;
+    }
+    if (op === OP_TEXT || op === OP_BINARY) {
+      if (this.frags.length) {
+        this.fail("a new message started before the last one finished");
+        return;
+      }
+      this.fragOp = op;
+    } else if (op !== OP_CONT) {
+      this.fail(`unknown opcode 0x${op.toString(16)}`);
+      return;
+    } else if (!this.fragOp) {
+      this.fail("a continuation frame with nothing to continue");
+      return;
+    }
+    this.fragLen += payload.length;
+    if (this.fragLen > MAX_MESSAGE) {
+      this.fail(`message longer than ${MAX_MESSAGE} bytes`);
+      return;
+    }
+    this.frags.push(payload);
+    if (!fin) return;
+    const body = this.frags.length === 1 ? this.frags[0] : Buffer.concat(this.frags);
+    const wasText = this.fragOp === OP_TEXT;
+    this.frags = [];
+    this.fragLen = 0;
+    this.fragOp = 0;
+    if (wasText) this.handlers.onText?.(body.toString("utf8"));
+    else this.handlers.onBinary?.(new Uint8Array(body));
+  }
+  /**
+   * A protocol violation: report it and close with 1002.
+   * @param why - what was wrong
+   */
+  fail(why) {
+    this.handlers.onError?.(new Error(why));
+    this.close(1002, why);
+  }
+  /**
+   * The connection is over: tell the owner once.
+   * @param code - the close code
+   * @param reason - the peer's reason
+   */
+  finish(code, reason) {
+    if (this.closed) return;
+    this.closed = true;
+    this.handlers.onClose?.(code, reason);
+  }
+};
+function encodeFrame(op, payload, mask) {
+  const len = payload.length;
+  const head = len < 126 ? 2 : len < 65536 ? 4 : 10;
+  const out = Buffer.alloc(head + (mask ? 4 : 0) + len);
+  out[0] = 128 | op;
+  if (len < 126) out[1] = len;
+  else if (len < 65536) {
+    out[1] = 126;
+    out.writeUInt16BE(len, 2);
+  } else {
+    out[1] = 127;
+    out.writeUInt32BE(0, 2);
+    out.writeUInt32BE(len, 6);
+  }
+  if (!mask) {
+    payload.copy(out, head);
+    return out;
+  }
+  out[1] = out[1] | 128;
+  const key = randomBytes(4);
+  key.copy(out, head);
+  for (let i = 0; i < len; i++) out[head + 4 + i] = payload[i] ^ key[i & 3];
+  return out;
+}
+function decodeFrame(buf, wantMask) {
+  if (buf.length < 2) return null;
+  const b0 = buf[0];
+  const b1 = buf[1];
+  if (b0 & 112) return new Error("reserved frame bits are set");
+  const fin = !!(b0 & 128);
+  const op = b0 & 15;
+  const masked = !!(b1 & 128);
+  if (masked !== wantMask)
+    return new Error(
+      wantMask ? "a client frame was not masked" : "a server frame was masked"
+    );
+  let len = b1 & 127;
+  let at = 2;
+  if (len === 126) {
+    if (buf.length < at + 2) return null;
+    len = buf.readUInt16BE(at);
+    at += 2;
+  } else if (len === 127) {
+    if (buf.length < at + 8) return null;
+    const hi = buf.readUInt32BE(at);
+    len = buf.readUInt32BE(at + 4);
+    at += 8;
+    if (hi) return new Error("frame longer than this end will read");
+  }
+  if (len > MAX_MESSAGE)
+    return new Error(`frame longer than ${MAX_MESSAGE} bytes`);
+  if (op >= 8 && (!fin || len > 125))
+    return new Error("a malformed control frame");
+  let key = null;
+  if (masked) {
+    if (buf.length < at + 4) return null;
+    key = buf.subarray(at, at + 4);
+    at += 4;
+  }
+  if (buf.length < at + len) return null;
+  const payload = Buffer.from(buf.subarray(at, at + len));
+  if (key) for (let i = 0; i < len; i++) payload[i] = payload[i] ^ key[i & 3];
+  return { fin, op, payload, size: at + len };
+}
+function acceptKey(key) {
+  return createHash("sha1").update(key + WS_GUID).digest("base64");
+}
+async function listenWs(host, port, onClient) {
+  const conns = /* @__PURE__ */ new Set();
+  const server = createServer((socket) => {
+    socket.setNoDelay(true);
+    let head = Buffer.alloc(0);
+    const onData = (chunk) => {
+      head = Buffer.concat([head, chunk]);
+      const end = head.indexOf("\r\n\r\n");
+      if (end < 0) {
+        if (head.length > 8192) socket.destroy();
+        return;
+      }
+      socket.off("data", onData);
+      const req = head.subarray(0, end).toString("utf8");
+      const rest = head.subarray(end + 4);
+      const key = /\r\nsec-websocket-key:[ \t]*(\S+)/i.exec(req)?.[1];
+      const upgrade = /\r\nupgrade:[ \t]*websocket/i.test(req);
+      if (!key || !upgrade || !/^GET /i.test(req)) {
+        socket.end(
+          "HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 46\r\n\r\nthis port serves a WebSocket gateway, not HTTP\n"
+        );
+        return;
+      }
+      socket.write(
+        `HTTP/1.1 101 Switching Protocols\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Accept: ${acceptKey(key)}\r
+\r
+`
+      );
+      const conn = new WsConnection(socket, false);
+      conns.add(conn);
+      socket.on("close", () => conns.delete(conn));
+      onClient({
+        conn,
+        from: `${socket.remoteAddress || "?"}:${socket.remotePort || 0}`
+      });
+      if (rest.length) setImmediate(() => socket.emit("data", rest));
+    };
+    socket.on("data", onData);
+    socket.on("error", () => socket.destroy());
+  });
+  await new Promise((res, rej) => {
+    server.once("error", rej);
+    server.listen(port, host, () => {
+      server.off("error", rej);
+      res();
+    });
+  });
+  const addr = server.address();
+  return {
+    port: typeof addr === "object" && addr ? addr.port : port,
+    host,
+    raw: server,
+    close: async () => {
+      for (const c of conns) c.close(CLOSE_NORMAL, "the gateway is stopping");
+      await new Promise((res) => server.close(() => res()));
+    }
+  };
+}
+async function connectWs(url) {
+  const u = new URL(url);
+  if (u.protocol !== "ws:")
+    throw new Error(
+      `${url}: only ws:// is supported here (wss:// needs a TLS front end)`
+    );
+  const port = Number(u.port || 80);
+  const key = randomBytes(16).toString("base64");
+  const socket = connect({ host: u.hostname, port });
+  socket.setNoDelay(true);
+  return new Promise((res, rej) => {
+    const fail = (e) => {
+      socket.destroy();
+      rej(e);
+    };
+    socket.once("error", fail);
+    socket.once("connect", () => {
+      socket.write(
+        `GET ${u.pathname || "/"}${u.search} HTTP/1.1\r
+Host: ${u.host}\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Key: ${key}\r
+Sec-WebSocket-Version: 13\r
+\r
+`
+      );
+      let head = Buffer.alloc(0);
+      const onData = (chunk) => {
+        head = Buffer.concat([head, chunk]);
+        const end = head.indexOf("\r\n\r\n");
+        if (end < 0) {
+          if (head.length > 8192)
+            fail(new Error(`${url}: no handshake answer`));
+          return;
+        }
+        socket.off("data", onData);
+        const res101 = head.subarray(0, end).toString("utf8");
+        if (!/^HTTP\/1\.1 101/i.test(res101)) {
+          fail(
+            new Error(
+              `${url}: the server refused the WebSocket upgrade (${res101.split("\r\n")[0]})`
+            )
+          );
+          return;
+        }
+        const accept = /\r\nsec-websocket-accept:[ \t]*(\S+)/i.exec(
+          res101
+        )?.[1];
+        if (accept !== acceptKey(key)) {
+          fail(new Error(`${url}: the handshake answer did not match the key`));
+          return;
+        }
+        socket.off("error", fail);
+        const rest = head.subarray(end + 4);
+        const conn = new WsConnection(socket, true);
+        if (rest.length) setImmediate(() => socket.emit("data", rest));
+        res(conn);
+      };
+      socket.on("data", onData);
+    });
+  });
+}
+
+// src/gateway.ts
+var DEFAULT_LISTEN = "127.0.0.1:6801";
+function parseListen(listen) {
+  const [dh, dp] = DEFAULT_LISTEN.split(":");
+  const text = String(listen || "").trim();
+  if (!text) return { host: dh, port: Number(dp) };
+  if (/^\d+$/.test(text)) return { host: dh, port: Number(text) };
+  const at = text.lastIndexOf(":");
+  if (at < 0) return { host: text, port: Number(dp) };
+  const host = text.slice(0, at) || dh;
+  const port = Number(text.slice(at + 1));
+  if (!Number.isInteger(port) || port < 0 || port > 65535)
+    throw new CliError(`--listen ${listen}: not a port number`);
+  return { host: host.replace(/^\[|\]$/g, ""), port };
+}
+async function startGateway(opts = {}) {
+  const log = opts.log || ((l) => process.stdout.write(`${l}
+`));
+  const candidates = opts.ports || await listPorts();
+  const device = choosePort(opts.port, candidates);
+  const opener = opts.opener || openSerialportBinding;
+  const { host, port } = parseListen(opts.listen || DEFAULT_LISTEN);
+  let client2 = null;
+  let serial = null;
+  let portOpen = false;
+  let opens = 0;
+  let pumping = false;
+  const dropCable = async (forget = false) => {
+    const s = serial;
+    const wasOpen = portOpen;
+    portOpen = false;
+    pumping = false;
+    if (forget) serial = null;
+    if (!s || !wasOpen) return;
+    try {
+      await s.close();
+    } catch {
+    }
+  };
+  const pump = async (s, conn, generation) => {
+    const reader = s.readable.getReader();
+    pumping = true;
+    while (pumping && opens === generation) {
+      let r;
+      try {
+        r = await reader.read();
+      } catch {
+        return;
+      }
+      if (r.done) return;
+      if (r.value && r.value.length && client2 === conn && opens === generation)
+        conn.sendBinary(r.value);
+    }
+  };
+  const handle = async (conn, req) => {
+    const id = req.id;
+    const reply = (body) => {
+      if (id === void 0) return;
+      conn.sendText(JSON.stringify({ id, ...body }));
+    };
+    try {
+      if (req.op === "open") {
+        await dropCable();
+        const s = serial || new NodeSerialPort(device, opener);
+        serial = s;
+        await s.open(req.config);
+        portOpen = true;
+        const generation = ++opens;
+        reply({ ok: true });
+        void pump(s, conn, generation);
+        return;
+      }
+      if (req.op === "close") {
+        await dropCable();
+        reply({ ok: true });
+        return;
+      }
+      if (req.op === "setSignals") {
+        if (!serial || !portOpen) throw new Error(`${device} is not open`);
+        await serial.setSignals(req.signals || {});
+        reply({ ok: true });
+        return;
+      }
+      if (req.op === "getSignals") {
+        if (!serial || !portOpen) {
+          reply({ ok: true, signals: null });
+          return;
+        }
+        reply({ ok: true, signals: await serial.getSignals() });
+        return;
+      }
+      throw new Error(`unknown op ${String(req.op)}`);
+    } catch (e) {
+      reply({ ok: false, error: e.message || String(e) });
+    }
+  };
+  const server = await listenWs(host, port, (c) => {
+    if (client2) {
+      log(`  refused ${c.from}: a client is already driving the cable`);
+      c.conn.on({});
+      c.conn.close(CLOSE_POLICY, "this gateway already has a client");
+      return;
+    }
+    client2 = c.conn;
+    log(`  client ${c.from} connected`);
+    let queue = Promise.resolve();
+    c.conn.on({
+      onText: (text) => {
+        let req;
+        try {
+          req = JSON.parse(text);
+        } catch {
+          c.conn.sendText(JSON.stringify({ ok: false, error: "not JSON" }));
+          return;
+        }
+        queue = queue.then(() => handle(c.conn, req));
+      },
+      onBinary: (bytes) => {
+        const s = serial;
+        if (!s || !portOpen) {
+          log(`  write of ${bytes.length} bytes with no port open, dropped`);
+          c.conn.sendText(
+            JSON.stringify({
+              event: "writeFailed",
+              error: `${device} is not open`
+            })
+          );
+          return;
+        }
+        const w = s.writable.getWriter();
+        w.write(bytes).catch((e) => {
+          const why = e.message || String(e);
+          log(`  write failed: ${why}`);
+          if (client2 === c.conn)
+            c.conn.sendText(
+              JSON.stringify({ event: "writeFailed", error: why })
+            );
+        });
+      },
+      onClose: () => {
+        if (client2 !== c.conn) return;
+        client2 = null;
+        log(`  client ${c.from} disconnected, cable closed`);
+        void dropCable(true);
+      }
+    });
+    c.conn.sendText(
+      JSON.stringify({ event: "hello", port: device, gateway: "bmweb" })
+    );
+  });
+  const shown = host === "0.0.0.0" || host === "::" ? host : host;
+  log(`gateway: ${device} served at ws://${shown}:${server.port}`);
+  log(
+    "  this is a byte pipe with no gate of its own: anyone who can reach this port can drive the car."
+  );
+  log(
+    host === "127.0.0.1" || host === "localhost" || host === "::1" ? "  listening on this machine only (--listen 0.0.0.0:PORT serves the LAN)" : "  listening beyond this machine; the port is open to whoever can route to it"
+  );
+  log("  one client at a time; the cable is closed when the client goes.");
+  return {
+    port: server.port,
+    host,
+    device,
+    stop: async () => {
+      await server.close();
+      client2 = null;
+      await dropCable(true);
+    }
+  };
+}
+async function gatewayCommand(opts = {}) {
+  const g = await startGateway(opts);
+  await new Promise((res) => {
+    const bye = () => {
+      process.off("SIGINT", bye);
+      process.off("SIGTERM", bye);
+      process.stdout.write("\ngateway: stopping, the cable is closed\n");
+      g.stop().then(res, res);
+    };
+    process.on("SIGINT", bye);
+    process.on("SIGTERM", bye);
+  });
+  return [];
+}
+
 // src/ipo.ts
-import { readdirSync, readFileSync as readFileSync3, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { basename, dirname as dirname2, join as join4, resolve } from "node:path";
 
 // src/table.ts
@@ -156,6 +1014,7 @@ var runtime_files_default = [
   "core/ipofile/decls.js",
   "core/ipofile/walk.js",
   "core/ipofile/exec.js",
+  "core/ipofile/encode.js",
   "core/ipofile/lex.js",
   "core/ipofile/parse.js",
   "core/ipofile/emit.js",
@@ -671,7 +1530,7 @@ function gatherIncludes(dirs, skip) {
   for (const dir of dirs) {
     let names;
     try {
-      names = readdirSync(dir);
+      names = readdirSync2(dir);
     } catch {
       throw new CliError(`include directory not found: ${dir}`);
     }
@@ -826,89 +1685,202 @@ function ipoKeys(file, includeDirs, menu, json) {
   if (!rows.length) return [`${s.stem}: no menu keys`];
   return formatTable(rows, ["MENU", "KEY", "LABEL", "OPENS", "JOBS", "WRITES"]);
 }
-function ipoCompile(file, includeDirs, out) {
+function ipoCompile(file, includeDirs, out, exec = false) {
   const R = loadRuntime();
   const name = basename(file);
   if (!R.ipofIsSource(name))
     throw new CliError(`${name}: compile takes a .IPS or .SRC source`);
   const s = readScript(file, includeDirs);
-  const target = out || join4(dirname2(resolve(file)), `${s.stem}.ipoexec.json`);
-  try {
-    writeFileSync2(target, JSON.stringify(s.exec));
-  } catch {
-    throw new CliError(`cannot write ${target}`);
+  const ext = exec ? "ipoexec.json" : "IPO";
+  const target = out || join4(dirname2(resolve(file)), `${s.stem}.${ext}`);
+  let wrote;
+  if (exec) {
+    try {
+      writeFileSync2(target, JSON.stringify(s.exec));
+    } catch {
+      throw new CliError(`cannot write ${target}`);
+    }
+    wrote = `wrote ${target} (the app's exec form; not INPA's binary .IPO)`;
+  } else {
+    let bytes;
+    try {
+      bytes = R.ipofEncode(s.exec);
+    } catch (err) {
+      throw new CliError(
+        `${name}: cannot write a .IPO -- ${err.message}`
+      );
+    }
+    try {
+      writeFileSync2(target, bytes);
+    } catch {
+      throw new CliError(`cannot write ${target}`);
+    }
+    wrote = `wrote ${target} (${bytes.length} bytes, INPA's .IPO container)`;
   }
   const inv = R.ipofInventory(s.exec);
   return [
     `${name}: compiled ${Object.keys(s.exec.procs).length} procedures (${inv.menus.length} menus, ${inv.screens.length} screens, ${inv.funcs.length} functions, ${inv.machines.length} state machines)` + (s.includes.length ? `, includes ${s.includes.join(", ")}` : ""),
-    `wrote ${target} (the app's exec form; not INPA's binary .IPO)`
+    wrote
   ];
 }
 
 // src/live.ts
 import { createInterface } from "node:readline";
 
-// src/serial.ts
-import { readdirSync as readdirSync2 } from "node:fs";
-var RX_KICK_MS = 4;
-var PORT_PATTERNS = [
-  /^cu\.usbserial/i,
-  /^cu\.SLAB/i,
-  /^cu\.wchusbserial/i,
-  /^ttyUSB/i,
-  /^ttyACM/i
-];
-var NodeSerialPort = class {
-  path;
-  opener;
-  binding = null;
-  /** chunks heard and not yet read */
+// src/gateway-client.ts
+var REPLY_MS = 1e4;
+function gatewayUrl(value) {
+  const text = String(value || "").trim();
+  if (!text) throw new CliError("--gateway needs a host:port or a ws:// URL");
+  if (/^wss?:\/\//i.test(text)) return text;
+  if (/^https?:\/\//i.test(text)) return text.replace(/^http/i, "ws");
+  return `ws://${text.includes(":") ? text : `${text}:6801`}`;
+}
+var GatewayPort = class {
+  url;
+  conn = null;
+  /** the device the host reports serving, for the cable chip */
+  device = "";
+  /** is a port open on the host */
+  opened = false;
+  /** chunks the host sent and no read has taken */
   chunks = [];
   /** reads waiting for bytes, oldest first, when the queue is empty */
   waiters = [];
-  /** the receive kick, running while a read waits (see startKick) */
-  kick = null;
-  /** a kick ioctl in flight, so they never pile up */
-  kicking = false;
-  /** the lines as last set, so a partial setSignals keeps the others */
-  lines = { dtr: false, rts: false, brk: false };
-  /** the wire trace sink, when the CLI wants one */
-  info;
+  /** control calls in flight, by the id they will be answered with */
+  pending = /* @__PURE__ */ new Map();
+  /** the next control message's id */
+  nextId = 1;
+  /** why the socket went, once it has */
+  gone = null;
+  /** the last write the host could not put on the wire */
+  writeError = null;
   /**
-   * @param path - the device path
-   * @param opener - how a binding is opened
-   * @param info - vendor and product ids, when known (portLabel shows them)
+   * @param url - the gateway's ws:// URL
    */
-  constructor(path, opener, info = {}) {
-    this.path = path;
-    this.opener = opener;
-    this.info = info;
+  constructor(url) {
+    this.url = url;
   }
-  /** Is a binding open (Web Serial's SerialPort.connected). */
+  /**
+   * Open the socket to the host. Called once, before the bus takes the
+   * port, so a gateway that is not there is reported before anything else.
+   * @returns nothing
+   */
+  async dial() {
+    let conn;
+    try {
+      conn = await connectWs(this.url);
+    } catch (e) {
+      throw new CliError(
+        `cannot reach the gateway at ${this.url}: ${e.message}`
+      );
+    }
+    this.conn = conn;
+    conn.on({
+      onText: (text) => this.onControl(text),
+      onBinary: (bytes) => this.push(bytes),
+      onClose: (code, reason) => {
+        this.gone = reason || (code === 1008 ? "the gateway already has a client" : "the gateway closed the connection");
+        this.opened = false;
+        this.wakeAll();
+        for (const p of this.pending.values())
+          p.rej(new Error(`the gateway connection ended: ${this.gone}`));
+        this.pending.clear();
+      }
+    });
+  }
+  /** Is a port open on the host (Web Serial's SerialPort.connected). */
   get connected() {
-    return !!this.binding;
+    return this.opened;
+  }
+  /** What the host is serving, for the cable chip. */
+  get remoteDevice() {
+    return this.device;
   }
   /**
-   * Open the device with the given settings.
+   * One control message from the host: a reply, or an event.
+   * @param text - the JSON frame
+   */
+  onControl(text) {
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (typeof msg.event === "string") {
+      if (msg.event === "hello" && typeof msg.port === "string")
+        this.device = msg.port;
+      if (msg.event === "writeFailed")
+        this.writeError = String(msg.error || "the write failed");
+      return;
+    }
+    const id = typeof msg.id === "number" ? msg.id : null;
+    if (id === null) return;
+    const p = this.pending.get(id);
+    if (!p) return;
+    this.pending.delete(id);
+    if (msg.ok === false)
+      p.rej(new Error(String(msg.error || "the gateway refused the call")));
+    else p.res(msg);
+  }
+  /**
+   * Send one control message and wait for its reply.
+   * @param op - the operation
+   * @param extra - the operation's fields
+   * @returns the reply
+   */
+  call(op, extra = {}) {
+    const conn = this.conn;
+    if (!conn || this.gone)
+      return Promise.reject(
+        new Error(
+          `the gateway connection is gone: ${this.gone || "not dialled"}`
+        )
+      );
+    const id = this.nextId++;
+    return new Promise((res, rej) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        rej(new Error(`the gateway did not answer ${op} in ${REPLY_MS} ms`));
+      }, REPLY_MS);
+      if (typeof timer === "object" && "unref" in timer) timer.unref();
+      this.pending.set(id, {
+        res: (v) => {
+          clearTimeout(timer);
+          res(v);
+        },
+        rej: (e) => {
+          clearTimeout(timer);
+          rej(e);
+        }
+      });
+      conn.sendText(JSON.stringify({ id, op, ...extra }));
+    });
+  }
+  /**
+   * Open the remote device with the given settings.
    * @param cfg - baud, bits, parity
    */
   async open(cfg) {
-    if (this.binding) throw new Error(`${this.path} is already open`);
-    const b = await this.opener(this.path, cfg);
-    this.binding = b;
+    await this.call("open", { config: cfg });
     this.chunks = [];
-    b.onData((chunk) => this.push(chunk));
+    this.writeError = null;
+    this.opened = true;
   }
-  /**
-   * Close the device: the binding goes, a waiting read is told `done`.
-   */
+  /** Close the remote device: a waiting read is told done. */
   async close() {
-    const b = this.binding;
-    this.binding = null;
-    this.stopKick();
+    this.opened = false;
     this.wakeAll();
     this.chunks = [];
-    if (b) await b.close();
+    if (!this.gone) await this.call("close");
+  }
+  /** Drop the socket itself, once the bus is finished with the port. */
+  hangUp() {
+    this.opened = false;
+    this.wakeAll();
+    if (this.conn && !this.gone) this.conn.close();
+    this.conn = null;
   }
   /** Tell every waiting read the port is done, and forget them. */
   wakeAll() {
@@ -917,7 +1889,7 @@ var NodeSerialPort = class {
     for (const w of ws) w({ value: void 0, done: true });
   }
   /**
-   * Bytes the binding heard: to the waiting read, else queued.
+   * Bytes the host streamed: to the waiting read, else queued.
    * @param chunk - the bytes
    */
   push(chunk) {
@@ -952,202 +1924,76 @@ var NodeSerialPort = class {
   }
   /**
    * One read: the next chunk, or `done` when the port is closed.
+   *
+   * Waiters queue, as they do on a local port: the bus races a read against
+   * a timeout and takes a fresh reader on every reopen, and a single waiter
+   * slot would orphan the abandoned read and hand its bytes to whichever
+   * handle happened to be held.
    * @returns the read result
    */
   read() {
     const next = this.chunks.shift();
     if (next) return Promise.resolve({ value: next, done: false });
-    if (!this.binding) return Promise.resolve({ value: void 0, done: true });
-    return new Promise((resolve2) => {
-      this.waiters.push(resolve2);
-      this.startKick();
-    });
-  }
-  /**
-   * Make the driver deliver what it has heard.
-   *
-   * THE BUG THIS FIXES. On macOS the built-in FTDI driver does not wake the
-   * reader when bytes arrive: with a read armed and the process simply
-   * waiting, an ECU's answer sat in the driver until some OTHER call touched
-   * the device (the next write, a modem-line change, close), and only then
-   * came out -- measured on a real car as 0 bytes for the first exchange
-   * after open and every later exchange delivering the PREVIOUS one's bytes
-   * at its start. Polling the modem lines (a TIOCMGET, no wire traffic)
-   * every few milliseconds while a read waits makes each answer arrive
-   * within the poll interval, first exchange included. The interval never
-   * holds the process open and stops itself once no read is waiting.
-   */
-  startKick() {
-    if (this.kick) return;
-    const tick = () => {
-      const b = this.binding;
-      if (!b || !this.waiters.length) {
-        this.stopKick();
-        return;
-      }
-      if (this.kicking) return;
-      this.kicking = true;
-      b.get().catch(() => null).then(() => {
-        this.kicking = false;
-      });
-    };
-    this.kick = setInterval(tick, RX_KICK_MS);
-    if (typeof this.kick === "object" && "unref" in this.kick)
-      this.kick.unref();
-  }
-  /** Stop the receive kick. */
-  stopKick() {
-    if (!this.kick) return;
-    clearInterval(this.kick);
-    this.kick = null;
+    if (!this.opened) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve2) => this.waiters.push(resolve2));
   }
-  /**
-   * Cancel the reader: a waiting read is told `done`, buffered bytes go.
-   */
+  /** Cancel the reader: a waiting read is told done, buffered bytes go. */
   cancel() {
     this.chunks = [];
     this.wakeAll();
   }
   /**
-   * Write bytes. Resolves when the OS has them, not when they have left the
-   * wire: the bus then holds DTR for the telegram's own byte time, and
-   * waiting for transmission here would double that hold and lose the
-   * ECU's answer (the reference interface's DtrTimeCorrCom is 0.3 ms).
+   * Write bytes. As on a local port this resolves when the bytes are on
+   * their way, not when they have left the car's wire: the bus then holds
+   * DTR for the telegram's own byte time, and waiting for more here would
+   * lengthen that hold and lose the ECU's answer.
    * @param bytes - the framed request
    */
   async write(bytes) {
-    if (!this.binding) throw new Error(`${this.path} is not open`);
-    await this.binding.write(bytes);
+    if (!this.opened) throw new Error(`${this.url} is not open`);
+    const conn = this.conn;
+    if (!conn) throw new Error(`the gateway connection is gone`);
+    const failed = this.writeError;
+    if (failed) {
+      this.writeError = null;
+      throw new Error(failed);
+    }
+    conn.sendBinary(bytes);
   }
   /**
-   * Drive the modem lines. A partial call keeps the lines it does not name,
-   * as Web Serial does; the binding always gets all three, because
-   * `serialport` would otherwise assert the ones left unsaid.
-   * @param s - the lines to set
-   */
-  async setSignals(s) {
-    if (!this.binding) throw new Error(`${this.path} is not open`);
-    if (s.dataTerminalReady !== void 0)
-      this.lines.dtr = !!s.dataTerminalReady;
-    if (s.requestToSend !== void 0) this.lines.rts = !!s.requestToSend;
-    if (s.break !== void 0) this.lines.brk = !!s.break;
-    await this.binding.set({ ...this.lines });
+   * Drive the remote modem lines. The host keeps the lines the call does
+   * not name, exactly as a local port does.
+   * @param s - the lines to set
+   */
+  async setSignals(s) {
+    if (!this.opened) throw new Error(`${this.url} is not open`);
+    await this.call("setSignals", { signals: s });
   }
   /**
-   * Read the modem lines (KL15 arrives on DSR or DCD of a K+DCAN cable).
-   * @returns the lines, or null when the binding cannot say
+   * Read the remote modem lines (KL15 arrives on DSR of a K+DCAN cable).
+   * @returns the lines, or null when the host cannot say
    */
   async getSignals() {
-    if (!this.binding) return null;
-    const st = await this.binding.get();
-    if (!st) return null;
-    return {
-      dataSetReady: !!st.dsr,
-      dataCarrierDetect: !!st.dcd,
-      clearToSend: !!st.cts
-    };
+    const r = await this.call("getSignals");
+    const sig = r.signals;
+    return sig || null;
   }
   /**
-   * The USB ids, for the bus's port label.
-   * @returns what is known
+   * The USB ids. A gateway does not forward them: the chip says where the
+   * cable is instead, which is the fact worth showing when it is not here.
+   * @returns nothing known
    */
   getInfo() {
-    return this.info;
+    return {};
   }
-  /** Web Serial's disconnect event; a pulled USB cable is not watched here. */
+  /** Web Serial's disconnect event; the socket's close stands in for it. */
   addEventListener() {
   }
 };
-var serialportModule = null;
-async function loadSerialport() {
-  if (serialportModule) return serialportModule;
-  try {
-    serialportModule = await import("serialport");
-  } catch {
-    throw new CliError(
-      "the serialport package is not installed; run: npm i -g serialport (or reinstall bmweb-cli with its optional dependencies)"
-    );
-  }
-  return serialportModule;
-}
-async function openSerialportBinding(path, cfg) {
-  const mod = await loadSerialport();
-  const port = new mod.SerialPort({
-    path,
-    baudRate: cfg.baudRate,
-    dataBits: cfg.dataBits,
-    stopBits: cfg.stopBits,
-    parity: cfg.parity,
-    autoOpen: false,
-    // keep the lines where we leave them across close/open
-    hupcl: false
-  });
-  await new Promise(
-    (res, rej) => port.open(
-      (e) => e ? rej(new CliError(`cannot open ${path}: ${e.message}`)) : res()
-    )
-  );
-  const call = (fn) => new Promise((res, rej) => fn((e) => e ? rej(e) : res()));
-  const binding = {
-    write: (bytes) => call((cb) => port.write(Buffer.from(bytes), cb)),
-    onData: (fn) => port.on("data", (b) => fn(new Uint8Array(b))),
-    set: (s) => call(
-      (cb) => port.set(
-        {
-          dtr: s.dtr,
-          rts: s.rts,
-          brk: s.brk,
-          cts: false,
-          dsr: false,
-          ...process.platform === "linux" ? { lowLatency: true } : {}
-        },
-        cb
-      )
-    ),
-    get: () => new Promise((res) => port.get((e, st) => res(e || !st ? null : st))),
-    close: () => new Promise((res) => port.close(() => res()))
-  };
-  await binding.set({ dtr: false, rts: false, brk: false });
-  return binding;
-}
-async function listPorts(devDir = "/dev") {
-  const found = /* @__PURE__ */ new Map();
-  try {
-    for (const name of readdirSync2(devDir))
-      if (PORT_PATTERNS.some((re) => re.test(name)))
-        found.set(`${devDir}/${name}`, "");
-  } catch {
-  }
-  try {
-    const mod = await loadSerialport();
-    for (const p of await mod.SerialPort.list()) {
-      const base = p.path.split("/").pop() || p.path;
-      if (!PORT_PATTERNS.some((re) => re.test(base))) continue;
-      const detail = [
-        p.manufacturer,
-        p.vendorId && p.productId ? `${p.vendorId}:${p.productId}` : "",
-        p.serialNumber ? `sn ${p.serialNumber}` : ""
-      ].filter(Boolean).join("  ");
-      found.set(p.path, detail);
-    }
-  } catch {
-  }
-  return [...found.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([path, detail]) => ({ path, detail }));
-}
-function choosePort(wanted, candidates) {
-  if (wanted) return wanted;
-  if (candidates.length === 1) return candidates[0].path;
-  if (!candidates.length)
-    throw new CliError(
-      "no K+DCAN cable found (looked for cu.usbserial*, cu.SLAB*, cu.wchusbserial*, ttyUSB*, ttyACM*); pass --port <device>"
-    );
-  throw new CliError(
-    `several ports found; pass --port: ${candidates.map((c) => c.path).join(", ")}`
-  );
-}
 
 // src/live.ts
 var FTDI_HINT = "If this is an FTDI cable, set its latency timer to 1 ms (Linux: done for you; macOS: FTDI D2XX/driver setting; Windows: Device Manager, Port Settings, Advanced).";
+var dialled = null;
 async function connectBus(opts = {}) {
   configureSite({
     ...opts.api ? { base: opts.api } : {},
@@ -1155,10 +2001,20 @@ async function connectBus(opts = {}) {
   });
   const R = loadRuntime();
   const g = runtimeGlobals();
-  const candidates = opts.ports || await listPorts();
-  const path = choosePort(opts.port, candidates);
-  const opener = opts.opener || openSerialportBinding;
-  const port = new NodeSerialPort(path, opener);
+  let port;
+  let path;
+  if (opts.gateway) {
+    const url = gatewayUrl(opts.gateway);
+    const remote = new GatewayPort(url);
+    await remote.dial();
+    dialled = remote;
+    port = remote;
+    path = url;
+  } else {
+    const candidates = opts.ports || await listPorts();
+    path = choosePort(opts.port, candidates);
+    port = new NodeSerialPort(path, opts.opener || openSerialportBinding);
+  }
   g.navigator.serial = {
     requestPort: async () => port,
     getPorts: async () => []
@@ -1167,8 +2023,14 @@ async function connectBus(opts = {}) {
   try {
     label = await R.webBus.connect();
   } catch (e) {
+    if (dialled === port) {
+      dialled.hangUp();
+      dialled = null;
+    }
     throw new CliError(`cannot open ${path}: ${e.message}`);
   }
+  if (port instanceof GatewayPort)
+    label = `gateway ${path}${port.remoteDevice ? ` (${port.remoteDevice})` : ""}`;
   return { R, label, path };
 }
 async function disconnectBus(R) {
@@ -1178,6 +2040,10 @@ async function disconnectBus(R) {
   } catch {
   }
   if (R.webBus.connected) await R.webBus.disconnect();
+  if (dialled) {
+    dialled.hangUp();
+    dialled = null;
+  }
 }
 async function portsCommand(json, ports) {
   const list = ports || await listPorts();
@@ -1199,6 +2065,22 @@ async function askYesNo(question, io = {}) {
   rl.close();
   return /^y(es)?$/i.test(answer.trim());
 }
+function filterResults(sets, want) {
+  const wanted = new Set(want.map((n) => n.toUpperCase()));
+  const seen = /* @__PURE__ */ new Set();
+  const out = sets.map((set) => {
+    const kept = {};
+    for (const [k, v] of Object.entries(set)) {
+      const up = k.toUpperCase();
+      if (!wanted.has(up)) continue;
+      seen.add(up);
+      kept[k] = v;
+    }
+    return kept;
+  });
+  const missing = want.filter((n) => !seen.has(n.toUpperCase()));
+  return { sets: out, missing };
+}
 async function jobCommand(sgbd, job, opts = {}) {
   const R = loadRuntime();
   const name = job.toUpperCase();
@@ -1227,6 +2109,17 @@ async function jobCommand(sgbd, job, opts = {}) {
 ${FTDI_HINT}` : ""}`
     );
   }
+  const want = (opts.results || []).filter((n) => n);
+  if (want.length) {
+    const f = filterResults(d.sets || [], want);
+    d = { ...d, sets: f.sets };
+    if (f.missing.length) {
+      const warn = opts.warn || ((l) => process.stderr.write(l + "\n"));
+      warn(
+        `bmweb: ${name} on ${target} returned no result named ${f.missing.join(", ")}`
+      );
+    }
+  }
   if (opts.json) return [JSON.stringify(d, null, 2)];
   return formatAnswer(d);
 }
@@ -1916,6 +2809,255 @@ function runSearch(query, opts) {
   return out;
 }
 
+// src/sgbd.ts
+function client(api) {
+  return api || runtimeGlobals().api;
+}
+async function dataFile(path, gzipped, api) {
+  if (api) return api(`/${path}`).catch(() => null);
+  const g = runtimeGlobals();
+  const load = gzipped ? g.webFetchGz : g.webFetchJson;
+  return load(path);
+}
+async function isGroupName(sgbd, api) {
+  const key = String(sgbd || "").trim().toLowerCase();
+  if (!key) return false;
+  const idx = await dataFile("data/groups/index.json", false, api).catch(
+    () => null
+  );
+  return !!idx && (idx.groups || []).includes(key);
+}
+async function loadGroupFile(name, api) {
+  const key = name.toLowerCase();
+  const doc = await dataFile(
+    `data/groups/${key}.json.gz`,
+    true,
+    api
+  );
+  if (!doc || typeof doc !== "object")
+    throw new CliError(
+      `the site lists group ${name} but serves no bytecode for it (data/groups/${key}.json.gz)`
+    );
+  return doc;
+}
+async function sgbdJobNames(sgbd, api) {
+  const target = sgbd.toLowerCase();
+  if (await isGroupName(target, api)) {
+    const doc2 = await loadGroupFile(target, api);
+    return Object.keys(doc2.jobs || {}).sort();
+  }
+  let doc;
+  try {
+    doc = await client(api)(`/api/ecu/${encodeURIComponent(target)}/jobs`);
+  } catch (e) {
+    throw new CliError(
+      `no module ${sgbd} on the site (${e.message})`
+    );
+  }
+  const list = Array.isArray(doc) ? doc : doc?.jobs || [];
+  const names = list.map(
+    (j) => typeof j === "string" ? j : String(j?.name || "")
+  ).filter((n) => n);
+  return [...new Set(names)].sort();
+}
+function normalizeResult(r) {
+  if (typeof r === "string") {
+    const at = r.indexOf(" : ");
+    const name2 = (at >= 0 ? r.slice(0, at) : r).trim();
+    return name2 ? { name: name2, comment: at >= 0 ? r.slice(at + 3).trim() : "" } : null;
+  }
+  const o = r;
+  const name = String(o?.name || "").trim();
+  if (!name) return null;
+  return { name, comment: String(o.comment || o.unit || "").trim() };
+}
+async function jobInfo(sgbd, job, api) {
+  const R = loadRuntime();
+  const target = sgbd.toLowerCase();
+  const name = job.toUpperCase();
+  const names = await sgbdJobNames(target, api);
+  if (!names.some((n) => n.toUpperCase() === name)) {
+    const near = names.filter((n) => n.toUpperCase().includes(name));
+    throw new CliError(
+      `${target} declares no job ${name}` + (near.length ? ` (did you mean ${near.slice(0, 6).join(", ")}?)` : ` (${names.length} jobs; bmweb sgbd jobs ${target} lists them)`)
+    );
+  }
+  const info = {
+    sgbd: target,
+    job: name,
+    write: R.isWriteJob(name),
+    args: [],
+    results: [],
+    comment: ""
+  };
+  if (await isGroupName(target, api)) return info;
+  const c = client(api);
+  const enc = encodeURIComponent(name);
+  const a = await c(`/api/ecu/${target}/arguments/${enc}`).catch(
+    () => null
+  );
+  const argRows = Array.isArray(a) ? a : a?.arguments || [];
+  info.args = argRows.map((x) => ({
+    name: String(x.ARG || x.name || "").trim(),
+    type: String(x.ARGTYPE || x.type || "").trim(),
+    // the exporter numbers a declaration's comment lines ARGCOMMENT0..n;
+    // they read as one sentence, so they are joined back into one
+    comment: Object.keys(x).filter((k) => /^ARGCOMMENT\d+$/.test(k)).sort(
+      (p, q) => Number(p.replace(/\D/g, "")) - Number(q.replace(/\D/g, ""))
+    ).map((k) => String(x[k] || "").trim()).filter((s) => s).join(" ")
+  })).filter((x) => x.name);
+  const r = await c(`/api/ecu/${target}/results/${enc}`).catch(() => null);
+  info.results = (Array.isArray(r) ? r : []).map(normalizeResult).filter((x) => !!x);
+  const jc = info.results.find((x) => /^JOB_?COMMENT/i.test(x.name));
+  info.comment = jc ? jc.comment : info.results[0]?.comment ?? "";
+  return info;
+}
+async function jobInfoCommand(sgbd, job, opts = {}) {
+  const info = await jobInfo(sgbd, job, opts.apiFn);
+  if (opts.json) return [JSON.stringify(info, null, 2)];
+  const out = [
+    `${info.sgbd} ${info.job}${info.write ? "  [WRITE]" : ""}`
+  ];
+  if (info.comment && info.comment !== info.results[0]?.comment)
+    out.push(info.comment);
+  out.push("", `arguments (${info.args.length})`);
+  out.push(
+    ...info.args.length ? formatTable(
+      info.args.map((a) => [a.name, a.type, a.comment]),
+      void 0,
+      "  "
+    ) : ["  none declared"]
+  );
+  out.push("", `results (${info.results.length})`);
+  out.push(
+    ...info.results.length ? formatTable(
+      info.results.map((r) => [r.name, r.comment]),
+      void 0,
+      "  "
+    ) : ["  none declared"]
+  );
+  return out;
+}
+var NAME_LIST_MAX = 6;
+function nameList(names) {
+  if (names.length <= NAME_LIST_MAX) return names.join(", ");
+  return `${names.slice(0, NAME_LIST_MAX).join(", ")}, +${names.length - NAME_LIST_MAX} more`;
+}
+async function sgbdJobsCommand(sgbd, opts = {}) {
+  const R = loadRuntime();
+  const target = sgbd.toLowerCase();
+  const names = await sgbdJobNames(target, opts.apiFn);
+  const group = await isGroupName(target, opts.apiFn);
+  const infos = group ? names.map((n) => ({
+    sgbd: target,
+    job: n,
+    write: R.isWriteJob(n),
+    args: [],
+    results: [],
+    comment: ""
+  })) : await Promise.all(names.map((n) => jobInfo(target, n, opts.apiFn)));
+  if (opts.json)
+    return [JSON.stringify({ sgbd: target, group, jobs: infos }, null, 2)];
+  if (!infos.length) return [`${target} declares no jobs`];
+  const rows = infos.map((i) => [
+    i.job,
+    nameList(i.args.map((a) => a.name)),
+    nameList(i.results.map((r) => r.name)),
+    // the first line only: a declaration's comment can run to a paragraph
+    // and a table row is one line
+    i.comment.split(/\r?\n/)[0].trim(),
+    i.write ? "yes" : ""
+  ]);
+  const out = formatTable(rows, [
+    "NAME",
+    "ARGS",
+    "RESULTS",
+    "COMMENT",
+    "WRITE"
+  ]);
+  const writes = infos.filter((i) => i.write).length;
+  out.push(
+    "",
+    `${formatCount(infos.length)} job${infos.length === 1 ? "" : "s"}, ${formatCount(writes)} the app would ask about before sending` + (group ? " (a group file carries job names, not declarations)" : "")
+  );
+  return out;
+}
+async function sgbdTables(sgbd, api) {
+  const target = sgbd.toLowerCase();
+  if (await isGroupName(target, api)) {
+    const doc2 = await loadGroupFile(target, api);
+    return doc2.tables || {};
+  }
+  const doc = await dataFile(
+    `data/sgbd-tables/${target}.json`,
+    false,
+    api
+  );
+  if (!doc || typeof doc !== "object") {
+    await sgbdJobNames(target, api);
+    return {};
+  }
+  return doc;
+}
+function tableColumns(rows) {
+  const cols = [];
+  for (const row of rows || [])
+    for (const k of Object.keys(row || {})) if (!cols.includes(k)) cols.push(k);
+  return cols;
+}
+async function sgbdTablesCommand(sgbd, opts = {}) {
+  const target = sgbd.toLowerCase();
+  const tabs = await sgbdTables(target, opts.apiFn);
+  const list = Object.keys(tabs).sort().map((name) => ({
+    name,
+    rows: (tabs[name] || []).length,
+    columns: tableColumns(tabs[name] || [])
+  }));
+  if (opts.json)
+    return [JSON.stringify({ sgbd: target, tables: list }, null, 2)];
+  if (!list.length) return [`${target} carries no lookup tables`];
+  const out = formatTable(
+    list.map((t) => [t.name, t.rows, t.columns.length, nameList(t.columns)]),
+    ["NAME", "ROWS", "COLS", "COLUMNS"]
+  );
+  out.push(
+    "",
+    `${formatCount(list.length)} table${list.length === 1 ? "" : "s"} (bmweb sgbd table ${target} <NAME> prints one)`
+  );
+  return out;
+}
+async function sgbdTableCommand(sgbd, name, opts = {}) {
+  const target = sgbd.toLowerCase();
+  const tabs = await sgbdTables(target, opts.apiFn);
+  const want = name.toUpperCase();
+  const key = Object.keys(tabs).find((k) => k.toUpperCase() === want);
+  if (!key) {
+    const near = Object.keys(tabs).filter((k) => k.toUpperCase().includes(want)).sort();
+    throw new CliError(
+      `${target} carries no table ${name}` + (near.length ? ` (did you mean ${near.slice(0, 6).join(", ")}?)` : ` (bmweb sgbd tables ${target} lists them)`)
+    );
+  }
+  const rows = tabs[key] || [];
+  if (opts.json)
+    return [JSON.stringify({ sgbd: target, table: key, rows }, null, 2)];
+  const cols = tableColumns(rows);
+  if (!cols.length) return [`${target} ${key}: no rows`];
+  const out = formatTable(
+    rows.map((r) => cols.map((c) => valueCell(r[c]))),
+    cols
+  );
+  out.push(
+    "",
+    `${formatCount(rows.length)} row${rows.length === 1 ? "" : "s"} in ${key}`
+  );
+  return out;
+}
+function valueCell(v) {
+  if (v == null) return "";
+  if (typeof v === "object") return JSON.stringify(v);
+  return String(v);
+}
+
 // src/tui.ts
 import { writeFileSync as writeFileSync4 } from "node:fs";
 import { createInterface as createInterface2, emitKeypressEvents } from "node:readline";
@@ -2749,7 +3891,7 @@ async function tuiCommand(chassis, sgbd, opts = {}) {
 }
 
 // src/bmweb.ts
-var VERSION = true ? "0.1.6" : "0.0.0-dev";
+var VERSION = true ? "0.1.7" : "0.0.0-dev";
 var INCLUDE = {
   include: {
     kind: "list",
@@ -2763,12 +3905,7 @@ var JSON_FLAG = {
     help: "print machine-readable JSON instead of a table"
   }
 };
-var LIVE = {
-  port: {
-    kind: "string",
-    alias: "p",
-    help: "the serial device (the single candidate when there is one)"
-  },
+var SITE2 = {
   api: {
     kind: "string",
     help: "the site the module data comes from (default https://bmweb.danner.ink/)"
@@ -2778,6 +3915,19 @@ var LIVE = {
     help: "fetch the module data again even when the cached copy is fresh"
   }
 };
+var LIVE = {
+  port: {
+    kind: "string",
+    alias: "p",
+    help: "the serial device (the single candidate when there is one)"
+  },
+  gateway: {
+    kind: "string",
+    alias: "g",
+    help: "drive a cable another machine is serving: host:port or a ws:// URL"
+  },
+  ...SITE2
+};
 var COMMANDS = {
   "ipo info": {
     usage: "bmweb ipo info <file.IPO|file.IPS|file.SRC> [-I dir]... [--json]",
@@ -2811,14 +3961,18 @@ var COMMANDS = {
     }
   },
   "ipo compile": {
-    usage: "bmweb ipo compile <file.IPS|file.SRC> [-I dir]... [-o out.ipoexec.json]",
-    summary: "compile an INPA source into the app's exec form (JSON); missing includes are named",
+    usage: "bmweb ipo compile <file.IPS|file.SRC> [-I dir]... [-o out.IPO] [--exec]",
+    summary: "compile an INPA source into a real .IPO (or --exec for the app's token form); missing includes are named",
     flags: {
       ...INCLUDE,
       out: {
         kind: "string",
         alias: "o",
-        help: "where to write (default: <stem>.ipoexec.json beside the source)"
+        help: "where to write (default: <stem>.IPO beside the source)"
+      },
+      exec: {
+        kind: "bool",
+        help: "write the app's exec form as JSON instead of .IPO bytes"
       }
     },
     async run(pos, flags) {
@@ -2830,7 +3984,8 @@ var COMMANDS = {
       return ipoCompile(
         file,
         flags.include || [],
-        flags.out
+        flags.out,
+        !!flags.exec
       );
     }
   },
@@ -2899,9 +4054,33 @@ var COMMANDS = {
       return portsCommand(!!flags.json);
     }
   },
+  gateway: {
+    usage: "bmweb gateway [--port p] [--listen host:port]",
+    summary: `serve this machine's cable over a WebSocket so another machine can drive it with --gateway (default ${DEFAULT_LISTEN})`,
+    flags: {
+      port: {
+        kind: "string",
+        alias: "p",
+        help: "the serial device (the single candidate when there is one)"
+      },
+      listen: {
+        kind: "string",
+        alias: "l",
+        help: `the address to serve on (default ${DEFAULT_LISTEN}; 0.0.0.0:6801 serves the LAN)`
+      }
+    },
+    async run(pos, flags) {
+      if (pos.length)
+        throw new CliError("usage: " + COMMANDS.gateway.usage);
+      return gatewayCommand({
+        port: flags.port,
+        listen: flags.listen
+      });
+    }
+  },
   job: {
-    usage: "bmweb job <sgbd> <JOB> [arg] [--port p] [--api url] [--yes] [--json]",
-    summary: "one raw job on one module over the cable, like the app's Tool32; a write needs --yes or a y answer",
+    usage: "bmweb job <sgbd> <JOB> [arg] [--results a,b] [--info] [--port p] [--gateway h:p] [--api url] [--yes] [--json]",
+    summary: "one raw job on one module over the cable, like the app's Tool32; a write needs --yes or a y answer, and --info reads the declaration instead of running it",
     flags: {
       ...LIVE,
       yes: {
@@ -2909,26 +4088,84 @@ var COMMANDS = {
         alias: "y",
         help: "consent to a write job on the command line"
       },
+      results: {
+        kind: "string",
+        alias: "r",
+        help: "comma-separated result names; only these print (case-insensitive)"
+      },
+      info: {
+        kind: "bool",
+        help: "what the SGBD declares about the job (arguments, results, comment); opens no port"
+      },
       ...JSON_FLAG
     },
     async run(pos, flags) {
       const [sgbd, job, arg] = pos;
       if (!sgbd || !job || pos.length > 3)
         throw new CliError("usage: " + COMMANDS.job.usage);
+      if (flags.info) {
+        if (arg !== void 0)
+          throw new CliError("--info takes no job argument (nothing is sent)");
+        useSite(flags);
+        return jobInfoCommand(sgbd, job, { json: !!flags.json });
+      }
       const { R } = await connectBus(liveOptions(flags));
       try {
         return await jobCommand(sgbd, job, {
           arg,
           yes: !!flags.yes,
-          json: !!flags.json
+          json: !!flags.json,
+          results: splitList(flags.results)
         });
       } finally {
         await disconnectBus(R);
       }
     }
   },
+  "sgbd jobs": {
+    usage: "bmweb sgbd jobs <sgbd> [--api url] [--refresh] [--json]",
+    summary: "every job an SGBD declares, with its arguments, results and comment, and which of them the app's write gate would ask about; no cable",
+    flags: { ...SITE2, ...JSON_FLAG },
+    async run(pos, flags) {
+      const sgbd = pos[0];
+      if (!sgbd || pos.length > 1)
+        throw new CliError(
+          "usage: " + COMMANDS["sgbd jobs"].usage
+        );
+      useSite(flags);
+      return sgbdJobsCommand(sgbd, { json: !!flags.json });
+    }
+  },
+  "sgbd tables": {
+    usage: "bmweb sgbd tables <sgbd> [--api url] [--refresh] [--json]",
+    summary: "every lookup table an SGBD carries for its bytecode, with row and column counts; no cable",
+    flags: { ...SITE2, ...JSON_FLAG },
+    async run(pos, flags) {
+      const sgbd = pos[0];
+      if (!sgbd || pos.length > 1)
+        throw new CliError(
+          "usage: " + COMMANDS["sgbd tables"].usage
+        );
+      useSite(flags);
+      return sgbdTablesCommand(sgbd, { json: !!flags.json });
+    }
+  },
+  "sgbd table": {
+    usage: "bmweb sgbd table <sgbd> <NAME> [--api url] [--refresh] [--json]",
+    summary: "one lookup table of an SGBD, its rows as a table; no cable",
+    flags: { ...SITE2, ...JSON_FLAG },
+    async run(pos, flags) {
+      const [sgbd, name] = pos;
+      if (!sgbd || !name || pos.length > 2)
+        throw new CliError(
+          "usage: " + COMMANDS["sgbd table"].usage
+        );
+      useSite(flags);
+      return sgbdTableCommand(sgbd, name, { json: !!flags.json });
+    }
+  },
   scan: {
-    usage: "bmweb scan <chassis> [--port p] [--api url] [--share] [--json]",
+    usage: "bmweb scan <chassis> [--port p] [--gateway h:p] [--api url] [--share] [--json]",
     summary: `INPA's whole-vehicle script over the cable (${SCAN_CHASSIS.join(" ")}): every fault memory as a report, --share adds a Garage link`,
     flags: {
       ...LIVE,
@@ -2960,7 +4197,7 @@ var COMMANDS = {
     }
   },
   tui: {
-    usage: "bmweb tui [<chassis> <sgbd>] [--port p] [--api url] [--menu m_x]",
+    usage: "bmweb tui [<chassis> <sgbd>] [--port p] [--gateway h:p] [--api url] [--menu m_x]",
     summary: "INPA screens in the terminal: the app's home (pick a chassis and a module) with no arguments, else that module; F-keys on the number row, every write asked first, released on quit",
     flags: {
       ...LIVE,
@@ -2991,10 +4228,20 @@ var COMMANDS = {
 function liveOptions(flags) {
   return {
     port: flags.port,
+    gateway: flags.gateway,
     api: flags.api,
     refresh: !!flags.refresh
   };
 }
+function useSite(flags) {
+  configureSite({
+    ...flags.api ? { base: flags.api } : {},
+    refresh: !!flags.refresh
+  });
+}
+function splitList(v) {
+  return String(v || "").split(",").map((s) => s.trim()).filter((s) => s);
+}
 function helpText() {
   const out = [
     `bmweb ${VERSION}: BMWeb's tools as a command line (https://bmweb.danner.ink/)`,
@@ -3012,10 +4259,12 @@ function helpText() {
     "  bmweb <command> --help    options of one command",
     "  bmweb --version",
     "",
-    "ports, job, scan and tui talk to the car over a K+DCAN cable (the serialport",
-    "package, an optional dependency). Module data and the search index are",
-    "fetched from the site and cached under $XDG_CACHE_HOME/bmweb-cli",
-    "(default ~/.cache/bmweb-cli) for a day; nothing BMW-derived ships here."
+    "ports, gateway, job, scan and tui talk to the car over a K+DCAN cable (the",
+    "serialport package, an optional dependency). One machine can own the cable",
+    "and serve it (bmweb gateway) while another drives it (--gateway host:port).",
+    "Module data and the search index are fetched from the site and cached under",
+    "$XDG_CACHE_HOME/bmweb-cli (default ~/.cache/bmweb-cli) for a day; nothing",
+    "BMW-derived ships here."
   );
   return out;
 }