bmweb-cli 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "bmweb-cli",
+  "version": "0.1.0",
+  "description": "BMWeb's tools as a command line: read INPA .IPO scripts, compile .IPS sources, search the corpus job index, decode and diff shared Garage reports, and, over a K+DCAN cable, run jobs, whole-car scans and INPA screens in the terminal.",
+  "license": "GPL-3.0-only",
+  "type": "module",
+  "bin": {
+    "bmweb": "dist/bmweb.js"
+  },
+  "files": [
+    "dist/",
+    "runtime/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dader34/BMWeb.git",
+    "directory": "cli"
+  },
+  "homepage": "https://bmweb.danner.ink/",
+  "bugs": {
+    "url": "https://github.com/dader34/BMWeb/issues"
+  },
+  "keywords": [
+    "bmw",
+    "inpa",
+    "diagnostics",
+    "ediabas",
+    "obd",
+    "cli"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync-runtime.mjs",
+    "build": "npm run sync && node scripts/build.mjs && tsc --noEmit -p tsconfig.json",
+    "test": "node --test dist-test/*.test.js",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.mjs\"",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "esbuild": "^0.28.2",
+    "prettier": "^3.9.6",
+    "typescript": "^7.0.2"
+  },
+  "optionalDependencies": {
+    "serialport": "^13.0.0"
+  }
+}

package/runtime/core/bestvm/codec.js

@@ -0,0 +1,285 @@
+/**
+ * @file Encodings the VM shares with its callers: CP1252 text <-> bytes,
+ * the engine's number parsers (StringToValue, float constants), the float
+ * formatter behind `flt2a`, little-endian byte folding, and the
+ * set_communication_pars decoder. Pure functions; no VM state.
+ *
+ * Best2Vm re-exposes the text and number codecs as static methods
+ * (machine.js) because callers outside the VM address them that way.
+ */
+
+/**
+ * The upper half of Windows-1252, the engine's ambient Encoding -- NOT
+ * latin-1. Bytes 0x80..0x9F are printable there (0x96 is an en dash), and
+ * decoding them as latin-1 control characters turned "LLR - Solldrehzahl"
+ * into a C1 escape. Index = byte - 0x80, value = the Unicode code point.
+ * @type {number[]}
+ */
+const CP1252_HIGH = [
+  0x20ac, 0x81, 0x201a, 0x0192, 0x201e, 0x2026, 0x2020, 0x2021, 0x02c6, 0x2030,
+  0x0160, 0x2039, 0x0152, 0x8d, 0x017d, 0x8f, 0x90, 0x2018, 0x2019, 0x201c,
+  0x201d, 0x2022, 0x2013, 0x2014, 0x02dc, 0x2122, 0x0161, 0x203a, 0x0153, 0x9d,
+  0x017e, 0x0178,
+];
+
+/** The byte a character outside CP1252 becomes when written back: '?'. */
+const CP1252_REPLACEMENT = 0x3f;
+
+/**
+ * Significant digits `flt2a` keeps: the engine's _floatPrecision default.
+ */
+const FLOAT_PRECISION = 4;
+
+/**
+ * Wire parameters decoded from a set_communication_pars blob (`xsetpar`).
+ * The transport reads the concept to frame, checksum and pace an exchange;
+ * the VM never touches the port itself.
+ * @typedef {Object} CommParams
+ * @property {number} concept - The protocol concept (1..6 K-line variants,
+ *   0x10B..0x10D KWP2000, 0x10F BMW-FAST, 0x110 D-CAN).
+ * @property {number} baud - Line speed in baud.
+ * @property {?number} timeout - Answer timeout (time to first byte), ms.
+ * @property {?number} regen - Regeneration gap between telegrams, ms.
+ * @property {?number} telEnd - Telegram-end / response-pending timeout, ms.
+ * @property {?number} timeoutNr78 - The 0x78 busy-wait timeout, ms.
+ * @property {number[]} params - The raw CommParameter words.
+ * @property {number[]} [answerLen] - set_answer_length pairs (`xawlen`).
+ * @property {number} [waitMs] - A `wait`/`waitex` pause owed before the
+ *   next exchange.
+ */
+
+/**
+ * Text and number codecs, namespaced so the pieces share one implementation.
+ */
+const Best2Codec = {
+  CP1252_HIGH,
+
+  /**
+   * Bytes -> text, CP1252.
+   * @param {Uint8Array|number[]} b - Raw bytes.
+   * @returns {string} The decoded text, one character per byte.
+   */
+  bytesStr(b) {
+    let s = '';
+    for (const x of b) {
+      s += String.fromCharCode(
+        x >= 0x80 && x <= 0x9f ? CP1252_HIGH[x - 0x80] : x
+      );
+    }
+    return s;
+  },
+
+  /**
+   * Text -> bytes, CP1252: the inverse of bytesStr, for text written back
+   * into a byte buffer. A character with no CP1252 byte becomes '?'.
+   * @param {string} str - The text.
+   * @returns {Uint8Array} One byte per character.
+   */
+  strBytesCp1252(str) {
+    const out = new Uint8Array(str.length);
+    for (let i = 0; i < str.length; i++) {
+      const c = str.charCodeAt(i);
+      if (c <= 0xff) {
+        out[i] = c;
+        continue;
+      }
+      const k = CP1252_HIGH.indexOf(c);
+      out[i] = k >= 0 ? 0x80 + k : CP1252_REPLACEMENT;
+    }
+    return out;
+  },
+
+  /**
+   * Any value -> CP1252 bytes of its string form (null/undefined -> empty).
+   * @param {*} s - The value to encode.
+   * @returns {Uint8Array} The encoded bytes.
+   */
+  strBytes(s) {
+    return Best2Codec.strBytesCp1252(String(s ?? ''));
+  },
+
+  /**
+   * NUL-terminated text, the way result strings are published: decode up to
+   * the first NUL byte.
+   * @param {Uint8Array|number[]} b - Raw bytes.
+   * @returns {string} The text before the first NUL.
+   */
+  cstr(b) {
+    const z = b.indexOf(0);
+    return Best2Codec.bytesStr(z < 0 ? b : b.slice(0, z));
+  },
+
+  /**
+   * EDIABAS's StringToValue: 0x hex, 0y binary, else decimal truncated at
+   * the first '.' or ','. Unparseable yields 0. This is what table cells
+   * are run through by tabseeku, so "0x10" seeks as 16.
+   *
+   * StringToValue uses Convert.ToInt64, which is ALL-OR-NOTHING: it
+   * throws on trailing junk and the caller catches it as 0. parseInt
+   * happily takes a valid prefix, and that difference is visible --
+   * y2bcd renders a non-BCD nibble as '*', so LSZ's ID_HW_NR is the text
+   * "2*", which the engine reports as 0 and parseInt would call 2.
+   * @param {*} s - The text to parse.
+   * @returns {number} The integer value, or 0.
+   */
+  strToValue(s) {
+    const t = String(s ?? '').replace(/\s+$/, '');
+    if (!t) return 0;
+    const low = t.toLowerCase();
+    if (low.startsWith('0x')) {
+      const body = t.slice(2);
+      if (!/^[0-9a-fA-F]+$/.test(body)) return 0;
+      const v = parseInt(body, 16);
+      return Number.isFinite(v) ? v : 0;
+    }
+    if (low.startsWith('0y')) {
+      const body = t.slice(2);
+      if (!/^[01]+$/.test(body)) return 0;
+      const v = parseInt(body, 2);
+      return Number.isFinite(v) ? v : 0;
+    }
+    if (low === '-' || low === '--') return 0;
+    if (/^[a-z]/i.test(low)) return 0; // a leading letter rejects it
+    // decimal, truncated at the first '.' or ',' -- then it must be a
+    // COMPLETE integer or the conversion fails
+    const cut = t.trimStart().split(/[.,]/)[0];
+    if (!/^[+-]?[0-9]+$/.test(cut)) return 0;
+    const v = parseInt(cut, 10);
+    return Number.isFinite(v) ? v : 0;
+  },
+
+  /**
+   * A float constant. EDIABAS writes them with either decimal separator.
+   * @param {*} s - The text to parse.
+   * @returns {number} The value, or 0 when it does not parse.
+   */
+  parseNum(s) {
+    if (s === undefined || s === null) return 0;
+    const v = parseFloat(String(s).replace(',', '.'));
+    return Number.isFinite(v) ? v : 0;
+  },
+
+  /**
+   * OpFlt2A, ported faithfully: round to floatPrecision (default 4)
+   * SIGNIFICANT digits (RoundToSignificantDigits, Math.Round = half-even),
+   * format invariant, then CUT THE STRING after the Nth digit character --
+   * including the engine's own quirk of truncating an exponent's digits.
+   * JS shortest-roundtrip formatting ("0.30000000000000004") never appears:
+   * the rounding and the cut both bound it.
+   * @param {number} value - The float to format.
+   * @returns {string} The engine's text for it.
+   */
+  fltText(value) {
+    const digits = FLOAT_PRECISION;
+    let v = Number(value);
+    if (Number.isFinite(v) && v !== 0) {
+      const scale = 10 ** (Math.floor(Math.log10(Math.abs(v))) + 1);
+      const x = (v / scale) * 10 ** digits;
+      let r = Math.round(x); // JS rounds half toward +inf...
+      if (Math.abs(x % 1) === 0.5 && r % 2 !== 0) r -= 1;
+      v = scale * (r / 10 ** digits); // ...Math.Round is half to even
+    }
+    let s = String(v);
+    const em = /^(-?[\d.]+)e([+-])(\d+)$/.exec(s);
+    if (em) s = `${em[1]}E${em[2]}${em[3].padStart(2, '0')}`;
+    let count = 0;
+    for (let i = 0; i < s.length; i++) {
+      if (s[i] >= '0' && s[i] <= '9') {
+        count++;
+        if (count >= digits) {
+          s = s.slice(0, i + 1);
+          break;
+        }
+      }
+    }
+    return s;
+  },
+
+  /**
+   * Fold `n` bytes at `offset` into an unsigned number, LITTLE-endian (byte
+   * 0 is the low byte), zero-padding when the slice is short -- the way
+   * Register.GetValueData and Operand.GetValueData assemble a value.
+   * @param {Uint8Array|number[]} buf - The bytes.
+   * @param {number} offset - Index of the low byte.
+   * @param {number} n - How many bytes to fold.
+   * @returns {number} The unsigned value.
+   */
+  leValue(buf, offset, n) {
+    let v = 0;
+    for (let k = n - 1; k >= 0; k--) v = v * 256 + (buf[offset + k] || 0);
+    return v;
+  },
+
+  /**
+   * Serialize an unsigned number as `n` bytes, LITTLE-endian (low byte
+   * first); higher bytes are dropped.
+   * @param {number} value - The value (already non-negative).
+   * @param {number} n - How many bytes to write.
+   * @returns {Uint8Array} The bytes.
+   */
+  leBytes(value, n) {
+    const out = new Uint8Array(n);
+    let v = value;
+    for (let k = 0; k < n; k++) {
+      out[k] = v & 0xff;
+      v = Math.floor(v / 256);
+    }
+    return out;
+  },
+
+  /**
+   * set_communication_pars, decoded the way EdInterfaceObd.cs reads it: the
+   * answer timeout, the regeneration gap and the response-pending timeout
+   * sit at a concept-specific index in the CommParameter words. The old
+   * "largest plausible timing word" guess picked ParTimeoutNr78 (5000 ms,
+   * the 0x78 busy-wait) as the answer timeout on every 0x1xx concept, so a
+   * silent KWP2000* probe cost 5 s where EDIABAS waits 500 ms -- the whole
+   * "MS45 takes ages to identify the first time".
+   *   concepts 1,2,3,5,6  (ISO 9141, KWP1281, DS1/DS2): [5] [6] [7]
+   *   0x10B/0x10C/0x10D   (KWP2000 std/BMW/*):          [2] [3] [4], Nr78 [7]
+   *   0x10F               (BMW-FAST):                    [2] [3] [4], Nr78 [6]
+   *   0x110               (D-CAN):                       [7] [8],     Nr78 [9]
+   * @param {number[]} words - The CommParameter words, concept first.
+   * @returns {CommParams} The decoded wire parameters.
+   */
+  decodeCommParams(words) {
+    const c = words[0];
+    const at = (i) => (i < words.length && words[i] > 0 ? words[i] : null);
+    let timeout = null,
+      regen = null,
+      telEnd = null,
+      timeoutNr78 = null;
+    if (c >= 0x1 && c <= 0x6) {
+      timeout = at(5);
+      regen = at(6);
+      telEnd = at(7);
+    } else if (c === 0x10b || c === 0x10c || c === 0x10d) {
+      timeout = at(2);
+      regen = at(3);
+      telEnd = at(4);
+      timeoutNr78 = at(7);
+    } else if (c === 0x10f) {
+      timeout = at(2);
+      regen = at(3);
+      telEnd = at(4);
+      timeoutNr78 = at(6);
+    } else if (c === 0x110) {
+      timeout = at(7);
+      regen = at(8);
+      timeoutNr78 = at(9);
+    }
+    return {
+      concept: c,
+      baud: words[1],
+      timeout,
+      regen,
+      telEnd,
+      timeoutNr78,
+      params: words,
+    };
+  },
+};
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { Best2Codec, CP1252_HIGH, FLOAT_PRECISION };
+}

package/runtime/core/bestvm/environment.js

@@ -0,0 +1,116 @@
+/**
+ * @file The job's environment: the constant pool, the argument list,
+ * shared-memory keys and SGBD table lookup. Extends Best2Vm (machine.js).
+ */
+
+if (typeof require === 'function' && typeof module !== 'undefined') {
+  Object.assign(globalThis, require('./machine.js'), require('./operands.js'));
+}
+
+/**
+ * A cell by column name, the exact name preferred and a case-insensitive
+ * match otherwise (TableNameDict is keyed on ToUpper; so are the column
+ * lookups of tabseek and tabget).
+ * @param {import('./machine.js').TableRow} row - The row.
+ * @param {string} col - The column name.
+ * @returns {string|undefined} The cell, or undefined when no column matches.
+ */
+function sgbdTableCell(row, col) {
+  if (row[col] !== undefined) return row[col];
+  const k = Object.keys(row).find(
+    (x) => x.toUpperCase() === String(col).toUpperCase()
+  );
+  return k === undefined ? undefined : row[k];
+}
+
+Object.assign(Best2Vm.prototype, {
+  /**
+   * A pool entry as TEXT: a byte-array literal is NUL-terminated text.
+   * @param {number} i - The constant-pool index.
+   * @returns {string} The text ('' for a missing entry).
+   */
+  lit(i) {
+    const v = this.code.strings[i];
+    if (Array.isArray(v)) return Best2Codec.cstr(Uint8Array.from(v));
+    return v ?? '';
+  },
+
+  /**
+   * A shared-data key. GetStringData stops at the first NUL, so a key that
+   * IS a NUL byte reads as the empty string -- which is a perfectly valid
+   * key, and the one MS450's AIF block uses. Uppercased, as the engine does.
+   * @param {import('./machine.js').Operand} op - The key operand.
+   * @returns {string} The key.
+   */
+  shmKey(op) {
+    const raw =
+      op[0] === OpMode.IMM_STR ? this.code.strings[op[1]] : this.bytes(op);
+    const bytes = Array.isArray(raw) ? Uint8Array.from(raw) : raw;
+    return Best2Codec.cstr(bytes).toUpperCase();
+  },
+
+  /**
+   * Job arguments split on ';'. An EMPTY argument string is ZERO
+   * parameters (GetActiveArgStrings only splits when length > 0), not one
+   * empty string -- otherwise `parn` reports 1 and every arg guard inverts.
+   * @returns {string[]} The arguments.
+   */
+  args() {
+    if (this._args === undefined) {
+      this._args = this.argText.length > 0 ? this.argText.split(';') : [];
+    }
+    return this._args;
+  },
+
+  /**
+   * Case-insensitive table lookup in the SGBD's own tables, with the exact
+   * name preferred.
+   * @param {string} name - The table name.
+   * @returns {?import('./machine.js').TableRow[]} The rows, or null.
+   */
+  findTable(name) {
+    if (!name) return null;
+    if (this.tables[name]) return this.tables[name];
+    const want = String(name).toUpperCase();
+    if (!this._tabIndex) {
+      this._tabIndex = new Map();
+      for (const k of Object.keys(this.tables)) {
+        this._tabIndex.set(k.toUpperCase(), this.tables[k]);
+      }
+    }
+    return this._tabIndex.get(want) || null;
+  },
+
+  /**
+   * A table in ANOTHER best file (`tabsetex "Name", "file"`). Both levels
+   * case-insensitive, like TableNameDict and the engine's file lookup.
+   * Per OpTabsetex (EdOperations.cs): a NON-empty file name switches the
+   * table stream to that file and looks the table up THERE -- there is no
+   * fallback to the current SGBD's own tables.
+   * @param {string} file - The bare best-file name.
+   * @param {string} name - The table name.
+   * @returns {?import('./machine.js').TableRow[]} The rows, or null.
+   */
+  findExtTable(file, name) {
+    if (!file || !name) return null;
+    const wantFile = String(file).toUpperCase();
+    let group = null;
+    for (const k of Object.keys(this.extTables)) {
+      if (k.toUpperCase() === wantFile) {
+        group = this.extTables[k];
+        break;
+      }
+    }
+    if (!group) return null;
+    if (group[name]) return group[name];
+    const want = String(name).toUpperCase();
+    for (const k of Object.keys(group)) {
+      if (k.toUpperCase() === want) return group[k];
+    }
+    return null;
+  },
+});
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { sgbdTableCell };
+}