bmweb-cli 0.1.0

package/runtime/core/webshim/native-bus.js

@@ -0,0 +1,108 @@
+/**
+ * @file The same bus, over the native bridge.
+ *
+ * A WKWebView has no Web Serial -- the desktop shell's web view does not offer
+ * that API -- so the shell owns the port and moves
+ * bytes for us (SerialProxy.cs). The framing, checksums and echo handling
+ * stay in exchange.js, identical to the Web Serial path; only the four
+ * primitives (open, write, read, flush) differ.
+ */
+/* exported NativeSerialBus */
+
+/**
+ * The transport behind the macOS shell's `window.bmacw` serial bridge.
+ * @extends SerialTransportBase
+ */
+class NativeSerialBus extends SerialTransportBase {
+  constructor() {
+    super();
+    /** @type {string|null} the device path the shell opened, or 'serial' */
+    this.path = null;
+    /** @type {PortConfig|null} */
+    this.config = null;
+  }
+
+  /** @returns {boolean} Is the shell holding a port open for us. */
+  get connected() {
+    return !!this.path;
+  }
+
+  /**
+   * Ask the shell to open its serial port at the K+DCAN default.
+   * @returns {Promise<string>} The port label.
+   */
+  async connect() {
+    const r = await window.bmacw.serialOpen(null, KDCAN.baudRate, KDCAN.parity);
+    this.path = (r && r.port) || 'serial';
+    this.config = KDCAN;
+    return this.portLabel();
+  }
+
+  /** @returns {string} The device name without its /dev/ prefix. */
+  portLabel() {
+    return (this.path || '').replace('/dev/', '');
+  }
+
+  /** Close the shell's port and forget it. */
+  async disconnect() {
+    try {
+      await window.bmacw.serialClose();
+    } catch {
+      /* already closed */
+    }
+    this.path = null;
+    this.config = null;
+  }
+
+  /**
+   * Reopen the port when a job's concept needs different wire settings --
+   * an E46 mixes 9600 8E1 body modules with a 115200 8N1 DME, and a port
+   * opened once at connect time can only speak to one of them.
+   * @param {PortConfig} cfg - The settings the next telegram needs.
+   */
+  async ensureConfig(cfg) {
+    if (this._configUnchanged(cfg)) return;
+    // Reopening the port drops the ECU session with it, so a woken module
+    // must be woken again. Without this a concept switch mid-job left
+    // `inited` set and every following request went to a sleeping ECU.
+    this._resetWakeState();
+    const r = await window.bmacw.serialOpen(
+      this.path === 'serial' ? null : this.path,
+      cfg.baudRate,
+      cfg.parity
+    );
+    this.path = (r && r.port) || this.path;
+    this.config = cfg;
+  }
+
+  // exchange() is inherited from SerialTransportBase (identical for every
+  // transport -- it delegates to the shared runExchange).
+
+  /**
+   * Write one framed request through the shell and read its answer.
+   *
+   * NOTE: the K-line wake (fast init / slow init) lives on WebSerialBus,
+   * which owns the break and DTR lines. The native bridge (window.bmacw)
+   * exposes no setSignals equivalent yet, so a K-line ECU reached through
+   * the desktop app still relies on the host side doing the wake.
+   * @param {number[]|null} framed - The request with its checksum, or null
+   *   to read a continuation frame without writing.
+   * @param {number} timeoutMs - ParTimeoutStd for this read.
+   * @param {CommParams} comm - The request's wire parameters.
+   * @returns {Promise<number[]>} The answer frame.
+   */
+  async exchangeRaw(framed, timeoutMs, comm) {
+    if (framed) {
+      // A stale partial frame from a timed-out job would be read as this
+      // job's answer, so start clean.
+      await window.bmacw.serialFlush();
+      await window.bmacw.serialWrite(framed);
+    }
+    return readFrame(
+      framed,
+      timeoutMs,
+      async () => window.bmacw.serialRead(),
+      comm
+    );
+  }
+}

package/runtime/core/webshim/timers.js

@@ -0,0 +1,82 @@
+/**
+ * @file The wire path's clock: a sleep that keeps time in a background tab.
+ *
+ * Run the app with no server: static JSON for data, Web Serial for the bus.
+ * The core/webshim/ folder replaces the two things the C# server did:
+ *   GET  /api/...        -> a frozen file in api/ (tools/web_export.py)
+ *   POST /api/.../run/X  -> the BEST2 VM (bestvm.js), talking to the cable
+ * The VM already runs a job against a `send(bytes)->bytes` callback, which is
+ * exactly a serial port; the shim only supplies the transport (framing,
+ * checksums, port settings). Loaded by every build; the C# hosts now only
+ * move bytes. Pieces, in load order:
+ *   timers.js            this file -- bmwSleep
+ *   trace.js             busTrace (ifh.trc) and apiTrace (api.trc)
+ *   framing.js           concepts, checksums, frame lengths, port settings
+ *   exchange.js          one request/answer with echo, pacing and retry
+ *   transport-base.js    the Transport contract and the shared serial base
+ *   native-bus.js        the macOS shell's serial bridge
+ *   web-serial-bus.js    Web Serial, with the K-line wake and DTR handling
+ *   bus.js               the one bus instance and the bus lock
+ *   data-fetch.js        JSON / gzip data loaders
+ *   job-runner.js        EDIABAS sessions and webRunJob
+ *   variant-resolver.js  group -> variant over the live bus
+ *   coding.js            the confirmed coding write entry
+ *   api-router.js        the fetch shim that answers /api/* locally
+ *   install.js           window exports and the bus-lock installation
+ */
+/* exported bmwSleep */
+
+/**
+ * Sleep `ms` milliseconds on a clock the browser does not throttle.
+ *
+ * TIMERS THAT KEEP TIME IN A BACKGROUND TAB. The browser throttles a hidden
+ * page's setTimeout to one wake per second (and further after minutes). The K-line
+ * exchange holds DTR for the telegram's byte time (a few ms), paces reads in
+ * single-digit ms and enforces a 25 ms regeneration gap -- each of which
+ * became a full second when the owner's tab was not in front, so a remote
+ * helper saw every job take ~1 s while the same tab in front took 150 ms. A
+ * dedicated worker's timers are not throttled that way: the bus's waits run
+ * there. Falls back to setTimeout where workers are unavailable (node, a
+ * blocked blob URL) so nothing else changes.
+ *
+ * Takes the wait in milliseconds (anything non-numeric or negative is 0)
+ * and resolves once it has elapsed.
+ *
+ * @type {(ms: number) => Promise<void>}
+ */
+const bmwSleep = (() => {
+  let worker = null;
+  let seq = 0;
+  const waits = new Map();
+  try {
+    if (typeof Worker !== 'undefined' && typeof Blob !== 'undefined') {
+      const src =
+        'onmessage=(e)=>{const{id,ms}=e.data;setTimeout(()=>postMessage(id),ms)}';
+      worker = new Worker(
+        URL.createObjectURL(new Blob([src], { type: 'text/javascript' }))
+      );
+      worker.onmessage = (e) => {
+        const r = waits.get(e.data);
+        if (r) {
+          waits.delete(e.data);
+          r();
+        }
+      };
+      worker.onerror = () => {
+        worker = null;
+        for (const r of waits.values()) r();
+        waits.clear();
+      };
+    }
+  } catch {
+    worker = null;
+  }
+  return (ms) =>
+    new Promise((r) => {
+      const t = Math.max(0, Number(ms) || 0);
+      if (!worker) return setTimeout(r, t);
+      const id = ++seq;
+      waits.set(id, r);
+      worker.postMessage({ id, ms: t });
+    });
+})();

package/runtime/core/webshim/trace.js

@@ -0,0 +1,205 @@
+/**
+ * @file Wire and API-layer tracing: the in-browser ifh.trc and api.trc.
+ *
+ * Off by default (zero cost: every call site is behind `busTrace.on`). Turn it
+ * on from the console with `busTrace.start()`, run the failing action, then
+ * `busTrace.dump()` to print what actually went over the wire. This exists
+ * because a transport bug is invisible from the error text alone -- IFH-0003
+ * says "the echo was wrong" without ever showing you the echo.
+ */
+/* exported busTrace, apiTrace */
+
+/** Rows kept while verbose tracing is on (busTrace.start's default). */
+const BUS_TRACE_LIMIT = 400;
+/** Rows kept in the always-on ring buffer of recent wire activity. */
+const BUS_TRACE_RECENT_LIMIT = 60;
+/** Job rows kept by the API-layer trace. */
+const API_TRACE_LIMIT = 500;
+
+/**
+ * One wire event.
+ * @typedef {object} BusTraceRow
+ * @property {number} t - Date.now() when it was recorded.
+ * @property {string} tag - 'tx', 'rx', 'err' or 'kline'.
+ * @property {string} hex - The bytes as upper-case hex pairs ('' when none).
+ * @property {number} n - Byte count.
+ * @property {string|undefined} note - Free text (timeouts, DTR holds, errors).
+ */
+
+/**
+ * The wire trace (EDIABAS's ifh.trc equivalent): every telegram sent and
+ * received, plus K-line control events, with a small always-on ring buffer so
+ * an IFH error can print the telegrams that led to it without anyone having
+ * run busTrace.start() first.
+ */
+const busTrace = {
+  on: false,
+  /** @type {BusTraceRow[]} */
+  rows: [],
+  limit: BUS_TRACE_LIMIT,
+  // A small ALWAYS-ON ring buffer of the most recent wire activity, kept even
+  // when verbose tracing is off (it is cheap -- a handful of {tag,hex,note}
+  // objects). When an IFH error surfaces to the user, dumpRecent() prints this
+  // so the failing telegrams are on the console without anyone having to have
+  // run busTrace.start() first.
+  /** @type {BusTraceRow[]} */
+  recent: [],
+  recentLimit: BUS_TRACE_RECENT_LIMIT,
+  /**
+   * Start verbose tracing, clearing the previous rows.
+   * @param {number} [limit] - Override the row cap for this run.
+   * @returns {string} A console-friendly acknowledgement.
+   */
+  start(limit) {
+    this.on = true;
+    this.rows = [];
+    if (limit) this.limit = limit;
+    console.log(
+      '[bus] tracing ON — reproduce the failure, then busTrace.dump()'
+    );
+    return 'tracing';
+  },
+  /**
+   * Stop verbose tracing; the rows stay for dump().
+   * @returns {string} A console-friendly acknowledgement.
+   */
+  stop() {
+    this.on = false;
+    return `tracing OFF (${this.rows.length} rows kept)`;
+  },
+  /**
+   * Record one wire event into the ring buffer and, while tracing, the rows.
+   * @param {string} tag - 'tx', 'rx', 'err' or 'kline'.
+   * @param {ArrayLike<number>|null} bytes - The telegram, or null for an event.
+   * @param {string} [note] - What happened (timeout, DTR hold, error text).
+   */
+  add(tag, bytes, note) {
+    const row = {
+      t: Date.now(),
+      tag,
+      hex: busTrace.hex(bytes),
+      n: bytes ? bytes.length : 0,
+      note,
+    };
+    // ring buffer: always on, bounded, drops the oldest
+    this.recent.push(row);
+    if (this.recent.length > this.recentLimit) this.recent.shift();
+    // verbose buffer: only while explicitly tracing
+    if (!this.on) return;
+    if (this.rows.length >= this.limit) return;
+    this.rows.push(row);
+  },
+  /**
+   * Print the recent ring buffer -- called automatically when an IFH error
+   * reaches the UI, or by hand. Labelled so it is obvious it is the auto-dump.
+   * @param {string} [why] - The error the dump precedes, for the group label.
+   */
+  dumpRecent(why) {
+    if (!this.recent.length) return;
+    const t0 = this.recent[0].t;
+    console.groupCollapsed(
+      `[bus] wire trace before ${why || 'error'} ` +
+        `(${this.recent.length} rows) — expand for telegrams`
+    );
+    console.table(busTrace.tableRows(this.recent, t0));
+    console.groupEnd();
+  },
+  /**
+   * Format bytes as upper-case hex pairs.
+   * @param {ArrayLike<number>|null|undefined} b - The bytes.
+   * @returns {string} 'AA BB CC', or '' for nothing.
+   */
+  hex(b) {
+    if (!b) return '';
+    return Array.from(b, (x) =>
+      (x & 0xff).toString(16).padStart(2, '0').toUpperCase()
+    ).join(' ');
+  },
+  /**
+   * Shape rows for console.table, with times relative to the first row.
+   * @param {BusTraceRow[]} rows - The rows to print.
+   * @param {number} t0 - The timestamp the `ms` column counts from.
+   * @returns {Array<{ms: number, what: string, len: number, bytes: string, note: string}>}
+   */
+  tableRows(rows, t0) {
+    return rows.map((r) => ({
+      ms: r.t - t0,
+      what: r.tag,
+      len: r.n,
+      bytes: r.hex,
+      note: r.note || '',
+    }));
+  },
+  /**
+   * Print the verbose rows collected since start().
+   * @returns {string|undefined} A row count, or nothing when there is no trace.
+   */
+  dump() {
+    if (!this.rows.length) {
+      console.log('[bus] nothing traced — busTrace.start() first');
+      return;
+    }
+    const t0 = this.rows[0].t;
+    console.table(busTrace.tableRows(this.rows, t0));
+    return `${this.rows.length} rows`;
+  },
+};
+if (typeof window !== 'undefined') window.busTrace = busTrace;
+
+/**
+ * One job run as the API layer saw it.
+ * @typedef {object} ApiTraceEntry
+ * @property {number} t - Date.now() when the job finished.
+ * @property {string} sgbd - The SGBD the job ran on.
+ * @property {string} job - The job name.
+ * @property {string|null} arg - Its argument string.
+ * @property {object[]} [sets] - The result sets on success.
+ * @property {string} [status] - JOB_STATUS of the first set.
+ * @property {string} [error] - The error message on failure.
+ */
+
+/**
+ * The API-LAYER trace: EDIABAS's api.trc equivalent. busTrace is ifh.trc (the
+ * raw telegrams); this is the layer above -- one row per job run, with its
+ * arguments, its result sets and the JOB_STATUS. Tool32's Trace window shows
+ * both layers; the wire tells you WHAT went over the bus, the API layer tells
+ * you what the JOB did with it. Recording is gated on `on` (Tool32's trace
+ * toggle sets it), matching how EDIABAS only writes the trace when the level
+ * is non-zero.
+ */
+const apiTrace = {
+  on: false,
+  /** @type {ApiTraceEntry[]} */
+  rows: [],
+  limit: API_TRACE_LIMIT,
+  /**
+   * Start recording job runs.
+   * @returns {string} A console-friendly acknowledgement.
+   */
+  start() {
+    this.on = true;
+    return 'api trace ON';
+  },
+  /**
+   * Stop recording; the rows stay.
+   * @returns {string} A console-friendly acknowledgement.
+   */
+  stop() {
+    this.on = false;
+    return 'api trace OFF';
+  },
+  /** Drop every recorded row. */
+  clear() {
+    this.rows = [];
+  },
+  /**
+   * Record one job: {sgbd, job, arg, sets, status, error}; the time is added.
+   * @param {Omit<ApiTraceEntry, 't'>} entry - The job's outcome.
+   */
+  add(entry) {
+    if (!this.on) return;
+    if (this.rows.length >= this.limit) return;
+    this.rows.push({ t: Date.now(), ...entry });
+  },
+};
+if (typeof window !== 'undefined') window.apiTrace = apiTrace;

package/runtime/core/webshim/transport-base.js

@@ -0,0 +1,128 @@
+/**
+ * @file The Transport contract every bus implements, and the base class the
+ * two serial transports share.
+ *
+ * TWO transports carry the exact same protocol to the car: Web Serial (a
+ * K+DCAN cable in a desktop browser) and the native bridge (the macOS shell
+ * owning /dev/tty). runExchange, readFrame, withChecksum, frameTotal and
+ * verifyChecksum (exchange.js, framing.js) are the protocol and are SHARED by
+ * both -- "the protocol does not change with the plumbing." A full merge of
+ * the two classes is NOT possible, because two boundaries are physical, not
+ * incidental, and each stays a per-transport override:
+ *
+ *   SEAM 1  connect-entry -- Web Serial needs a USER GESTURE for the first
+ *           requestPort(); the native bridge does not.
+ *   SEAM 2  K-line line-control -- only Web Serial has setSignals (DTR/break),
+ *           so fast-init and the ISO 9141 slow-init live there alone; the
+ *           native bridge has no setSignals.
+ *
+ * The native correspondence lives in C# (a different runtime, not unified
+ * here): SerialProxy.cs is the byte-mover behind NativeSerialBus (open/write/
+ * readAvailable/close/flush). Bytes cross that bridge as a JSON int[]
+ * (BmacwBridge.cs AsNumberArray), NOT base64 -- base64 corrupted the
+ * echo/checksum. src/EdiabasMac is LEGACY (its InpaMac.Api server is deleted);
+ * it is reference for what JS reimplemented, not a transport, and is
+ * deliberately NOT part of this interface.
+ */
+/* exported SerialTransportBase */
+
+/**
+ * KL30/KL15 as the cable reports them.
+ * @typedef {object} BusState
+ * @property {number|null} battery - Volts, or null when off/unknown.
+ * @property {boolean|null} ignition - KL15, or null when unknown.
+ * @property {boolean} [derived] - True when the port cannot report its
+ *   signals and the nominal "on" was assumed.
+ * @property {boolean} [sensed] - True when the value came off a modem line.
+ */
+
+/**
+ * Every transport MUST expose this surface (the rest of the renderer --
+ * app.js, coding-write.js, the fetch shim -- calls only these). runExchange
+ * also reads/writes sessionConcept, lastResponseAt, inited and initedAddr as
+ * shared session state.
+ * @typedef {object} Transport
+ * @property {boolean} connected - Is the wire up right now.
+ * @property {() => Promise<string>} connect - Open the wire (SEAM 1); returns
+ *   the port label.
+ * @property {() => Promise<string|null>} [reconnect] - Silent reopen on load,
+ *   no gesture (Web Serial only); null when nothing was previously granted.
+ * @property {(cfg: PortConfig) => Promise<void>} ensureConfig - Make
+ *   baud+parity match a concept.
+ * @property {(out: ArrayLike<number>, comm: CommParams) => Promise<number[]>} exchange -
+ *   One request/answer -- SHARED, it just calls runExchange(this, ...).
+ * @property {(framed: number[]|null, timeoutMs: number, comm: CommParams) => Promise<number[]>} exchangeRaw -
+ *   Write+read one frame (SEAM 2); framed null re-reads a continuation.
+ * @property {() => Promise<void>} disconnect - Tear the wire down.
+ * @property {() => Promise<BusState>} [readState] - KL30/KL15 (absent on
+ *   the native bridge -- callers guard).
+ * @property {() => string} portLabel - A human name for the chip.
+ * @property {number|null} sessionConcept - The concept of the last telegram.
+ * @property {number|null|undefined} lastResponseAt - Date.now() of the last
+ *   answer, for ParRegenTime pacing.
+ * @property {boolean|null} inited - Whether the K-line wake has run on this
+ *   port session.
+ * @property {number|null} initedAddr - The address the ISO 9141 wake was
+ *   done for.
+ */
+
+/**
+ * Shared base for the two SERIAL transports (Web Serial + native bridge). They
+ * both own a real port whose baud/parity must track the job's concept, and
+ * they both keep the same per-session wire state -- so the reconfigure-guard
+ * and the state reset live here once.
+ */
+class SerialTransportBase {
+  /**
+   * Clear the full wire state, when the session on the wire ENDS (connect,
+   * reconnect, disconnect): a fresh cable has woken nothing and remembers no
+   * concept.
+   */
+  _resetWireState() {
+    this.inited = null;
+    this.initedAddr = null;
+    this.pending = null;
+    this.sessionConcept = null;
+  }
+
+  /**
+   * Clear the WAKE state only, when the port is REOPENED onto different
+   * settings: a reopened port drops the ECU session, so a woken module must
+   * be woken again. Deliberately does NOT touch sessionConcept -- runExchange
+   * sets that immediately before calling ensureConfig, and the K-line wake in
+   * exchangeRaw reads it right after, so clearing it here would blind the
+   * wake.
+   */
+  _resetWakeState() {
+    this.inited = null;
+    this.initedAddr = null;
+  }
+
+  /**
+   * True when a requested config already matches the open port, so
+   * ensureConfig can skip the (session-dropping) reopen. Baud and parity are
+   * the only settings a concept changes; data/stop bits are constant here.
+   * @param {PortConfig} cfg - The settings the next telegram needs.
+   * @returns {boolean}
+   */
+  _configUnchanged(cfg) {
+    return (
+      !!this.config &&
+      this.config.baudRate === cfg.baudRate &&
+      this.config.parity === cfg.parity
+    );
+  }
+
+  /**
+   * One request/answer exchange. IDENTICAL for every transport -- the retry,
+   * pacing, response-pending and framing all live in runExchange, which
+   * drives the transport through its exchangeRaw/ensureConfig overrides. Kept
+   * in the base so there is exactly one copy.
+   * @param {ArrayLike<number>} out - The request without its checksum.
+   * @param {CommParams} comm - Its wire parameters.
+   * @returns {Promise<number[]>} The answer frame.
+   */
+  async exchange(out, comm) {
+    return runExchange(this, out, comm);
+  }
+}