@alotop/dsh-matlab-bridge 0.1.1

package/python/ml_driver.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""DSH MATLAB bridge driver.
+
+Owns exactly one persistent MATLAB Engine session and speaks newline-delimited
+JSON on stdin/stdout.
+
+Why every protocol line carries an `@@DSH:` prefix: the MATLAB Engine forwards
+the MATLAB command window to this process's stdout, so a bare JSON protocol
+would race with MATLAB's own output. Lines carrying the prefix are protocol;
+every other line is MATLAB chatter that the caller can surface as diagnostics.
+
+Request:  {"id": <int>, "op": "<name>", ...}
+Response: {"id": <int>, "ok": <bool>, ...}
+
+Ops
+  ping                                  liveness + whether MATLAB is up
+  start                                 launch MATLAB (idempotent)
+  eval    {code}                        run code in the base workspace
+  debug   {action, ...}                 breakpoints, stepping, frame inspection
+  figure  {action, ...}                 list, export and close figures
+  shutdown                              quit MATLAB and exit
+
+Figure actions
+  list                                  every open figure, in creation order
+  save    {figure, dir}                 export to PNG; figure=0 means all
+  close   {figure}                      close one figure, or all when 0
+
+Debug actions
+  break       {file, line}              dbstop in <file> at <line>
+  breakError                            dbstop if error
+  clearBreaks                           dbclear all
+  run         {code, waitMs}            launch code; stop when it pauses or ends
+  status                                paused?, stack text, future running?
+  stack                                 dbstack text of the paused frame
+  vars                                  whos text of the paused frame
+  get         {name}                    value of NAME in the paused frame
+  eval        {code}                    evaluate CODE in the paused frame
+  step | stepIn | stepOut | continue    dbstep / dbcont
+  quit                                  dbquit
+  finish      {waitMs}                  await the outstanding run
+"""
+
+import json
+import os
+import sys
+import time
+import warnings
+
+# The bundled engine advertises Python 3.9-3.12 and warns on 3.13. The shipped
+# abi3 module loads and runs correctly on 3.13, so the warning is pure noise on
+# the stderr channel the caller surfaces as diagnostics.
+warnings.filterwarnings("ignore", message=".*MATLAB Engine for Python supports Python version.*")
+warnings.filterwarnings("ignore", message=".*Python versions .* are supported.*")
+
+
+# Import the engine without depending on the caller setting PYTHONPATH. The
+# Cordis plugin spawns this file through the subprocess seam, where building a
+# full environment is awkward; a self-contained driver removes that coupling.
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_PYLIBS = os.path.join(_HERE, "pylibs")
+if os.path.isdir(_PYLIBS) and _PYLIBS not in sys.path:
+    sys.path.insert(0, _PYLIBS)
+
+# Speak protocol over the raw byte streams with an explicit encoding. The
+# Windows console code page is not UTF-8, and MATLAB output here is routinely
+# non-ASCII (localized error messages), so relying on the locale would corrupt
+# both the JSON and the captured text.
+_STDIN = sys.stdin.buffer
+_STDOUT = sys.stdout.buffer
+
+PROTOCOL_PREFIX = "@@DSH:"
+
+_engine = None
+_future = None
+_last_run_error = None
+
+
+def emit(payload):
+    """Write one protocol line. A dead pipe ends the process quietly."""
+    try:
+        line = PROTOCOL_PREFIX + json.dumps(payload, ensure_ascii=False)
+        _STDOUT.write(line.encode("utf-8", "replace") + b"\n")
+        _STDOUT.flush()
+    except Exception:
+        raise SystemExit(0)
+
+
+def engine():
+    """Return the live MATLAB engine, starting it on first use."""
+    global _engine
+    if _engine is None:
+        try:
+            import matlab.engine
+        except ImportError as exc:
+            # A bare ImportError here is the single most likely first-run
+            # failure, and it names neither the cause nor the fix.
+            raise RuntimeError(
+                "the MATLAB Engine for Python runtime is not available (%s). "
+                "Lay it out from your MATLAB installation first: "
+                "`npx @alotop/dsh-matlab-bridge` (or `npm run setup` in a "
+                "checkout). It was expected under %s." % (exc, _PYLIBS)
+            )
+        _engine = matlab.engine.start_matlab("-nodesktop")
+        # dsh_evalbase lives beside this driver; MATLAB must be able to see it.
+        helpers = os.path.join(os.path.dirname(os.path.abspath(__file__)), "mfiles")
+        _engine.addpath(helpers, nargout=0)
+    return _engine
+
+
+def capture(code):
+    """Run CODE in the MATLAB base workspace; return (out, err, stack)."""
+    result = engine().dsh_evalbase(code, nargout=1)
+    out = result.get("out", "") or ""
+    err = result.get("err", "") or ""
+    stack = result.get("stack", "") or ""
+    return out, err, stack
+
+
+def control(command):
+    """Run a debugger control statement; return (out, err).
+
+    These are command-syntax statements (`dbstop in f at 4`), never expressions,
+    so they bypass the base-workspace capture helper and go straight to the
+    engine, which runs them with no output argument.
+    """
+    try:
+        engine().eval(command, nargout=0)
+        return "", ""
+    except Exception as exc:  # noqa: BLE001
+        return "", str(exc)
+
+
+def dbstack_text():
+    """Command-window text of the current stack, empty when not debugging."""
+    try:
+        return engine().eval("evalc('dbstack')", nargout=1) or ""
+    except Exception as exc:  # noqa: BLE001
+        return ""
+
+def is_paused():
+    return dbstack_text().strip() != ""
+
+
+def await_future(wait_ms):
+    """Wait up to WAIT_MS for the outstanding run; return its outcome string."""
+    global _future, _last_run_error
+    if _future is None:
+        return "no-run"
+    deadline = time.time() + (wait_ms / 1000.0)
+    while time.time() < deadline:
+        if _future.done():
+            try:
+                _future.result()
+                _future = None
+                return "completed"
+            except Exception as exc:  # noqa: BLE001
+                _last_run_error = str(exc)
+                _future = None
+                return "failed"
+        time.sleep(0.05)
+    return "running"
+
+
+def op_eval(req):
+    code = req.get("code", "")
+    if not code.strip():
+        return {"ok": True, "out": "", "err": "", "stack": ""}
+    out, err, stack = capture(code)
+    return {"ok": err == "", "out": out, "err": err, "stack": stack}
+
+
+def op_debug(req):
+    global _future, _last_run_error
+    action = req.get("action", "")
+    eng = engine()
+
+    if action == "break":
+        name = (req.get("file") or "").strip()
+        if not name:
+            return {"ok": False, "err": "debug break requires 'file'"}
+        line = req.get("line")
+        command = "dbstop in %s at %d" % (name, int(line)) if line else "dbstop in %s" % name
+        out, err = control(command)
+        return {"ok": err == "", "out": out, "err": err}
+
+    if action == "breakError":
+        out, err = control("dbstop if error")
+        return {"ok": err == "", "out": out, "err": err}
+
+    if action == "clearBreaks":
+        out, err = control("dbclear all")
+        return {"ok": err == "", "out": out, "err": err}
+
+    if action == "run":
+        code = (req.get("code") or "").strip()
+        if not code:
+            return {"ok": False, "err": "debug run requires 'code'"}
+        wait_ms = int(req.get("waitMs") or 8000)
+        _last_run_error = None
+        _future = eng.eval(code, background=True, nargout=0)
+        deadline = time.time() + (wait_ms / 1000.0)
+        while time.time() < deadline:
+            # Check completion before probing the stack: a query issued while
+            # MATLAB is busy running the background call blocks until that call
+            # yields, so testing `done` first reports a fast run immediately.
+            if _future.done():
+                try:
+                    _future.result()
+                    _future = None
+                    return {"ok": True, "state": "completed", "out": ""}
+                except Exception as exc:  # noqa: BLE001
+                    _future = None
+                    return {"ok": False, "state": "failed", "err": str(exc)}
+            if is_paused():
+                return {"ok": True, "state": "paused", "stack": dbstack_text()}
+            time.sleep(0.1)
+        return {"ok": True, "state": "running", "stack": dbstack_text()}
+
+    if action == "status":
+        paused = is_paused()
+        stack = dbstack_text() if paused else ""
+        running = _future is not None and not _future.done()
+        payload = {"ok": True, "paused": paused, "running": running, "stack": stack}
+        if _future is not None and _future.done():
+            payload["finished"] = True
+        return payload
+
+    if action == "stack":
+        if not is_paused():
+            return {"ok": False, "err": "MATLAB is not paused at a breakpoint"}
+        return {"ok": True, "out": dbstack_text()}
+
+    if action == "vars":
+        if not is_paused():
+            return {"ok": False, "err": "MATLAB is not paused at a breakpoint"}
+        return {"ok": True, "out": eng.eval("evalc('whos')", nargout=1) or ""}
+
+    if action in ("get", "eval"):
+        if not is_paused():
+            return {"ok": False, "err": "MATLAB is not paused at a breakpoint"}
+        code = req.get("name") if action == "get" else req.get("code")
+        if not code:
+            return {"ok": False, "err": "debug %s requires a value" % action}
+        try:
+            value = eng.eval(str(code))
+        except Exception as exc:  # noqa: BLE001
+            return {"ok": False, "err": str(exc)}
+        return {"ok": True, "out": _format_value(value)}
+
+    if action in ("step", "stepIn", "stepOut", "continue", "quit"):
+        if not is_paused():
+            return {"ok": False, "err": "MATLAB is not paused at a breakpoint"}
+        command = {
+            "step": "dbstep",
+            "stepIn": "dbstep in",
+            "stepOut": "dbstep out",
+            "continue": "dbcont",
+            "quit": "dbquit",
+        }[action]
+        try:
+            eng.eval(command, nargout=0)
+        except Exception as exc:  # noqa: BLE001
+            return {"ok": False, "err": str(exc)}
+        if action == "continue":
+            outcome = await_future(int(req.get("waitMs") or 15000))
+            return {"ok": True, "state": outcome, "err": _last_run_error or ""}
+        if action == "quit":
+            _future = None
+            return {"ok": True, "state": "debug-quit"}
+        return {"ok": True, "state": "paused", "stack": dbstack_text()}
+
+    if action == "finish":
+        outcome = await_future(int(req.get("waitMs") or 15000))
+        return {"ok": True, "state": outcome, "err": _last_run_error or ""}
+
+    return {"ok": False, "err": "unknown debug action: %s" % action}
+
+
+def _format_value(value):
+    """Render a MATLAB value for the model without dumping it as Python repr."""
+    if value is None:
+        return ""
+    if isinstance(value, float):
+        return repr(value)
+    if isinstance(value, (int, bool, str)):
+        return str(value)
+    try:
+        text = engine().eval("evalc('disp(value)')", nargout=1)
+        return text or str(value)
+    except Exception:  # noqa: BLE001
+        return str(value)
+
+
+def _load_json(payload, label):
+    """Parse the JSON text a MATLAB helper returned."""
+    try:
+        return json.loads(payload)
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError("MATLAB %s returned unparsable JSON: %s" % (label, exc))
+
+
+def _figure_records(payload, label):
+    """Normalize a MATLAB figure payload into a list of record dicts.
+
+    JSONENCODE emits a bare OBJECT when the struct array holds exactly one
+    element and an ARRAY otherwise, so both shapes are legitimate. Iterating the
+    object directly would walk its KEY names instead of its records, which is
+    why this normalizes before any caller sees it.
+    """
+    parsed = _load_json(payload, label)
+    if isinstance(parsed, dict):
+        return [parsed]
+    if isinstance(parsed, list):
+        return [entry for entry in parsed if isinstance(entry, dict)]
+    return []
+
+
+def _figure_record(entry):
+    """Reduce one MATLAB figure record to the scalars the caller needs."""
+    if not isinstance(entry, dict):
+        return {"number": None, "name": "", "visible": "", "path": "", "error": ""}
+    number = entry.get("number")
+    return {
+        "number": int(number) if isinstance(number, (int, float)) else None,
+        "name": str(entry.get("name") or ""),
+        "visible": str(entry.get("visible") or ""),
+        "path": str(entry.get("path") or ""),
+        "error": str(entry.get("error") or ""),
+    }
+
+
+def op_figure(req):
+    action = req.get("action", "save")
+    # Validate before touching the engine: a typo must not pay a MATLAB launch.
+    if action not in ("list", "save", "close"):
+        return {"ok": False, "err": "unknown figure action: %s" % action}
+    eng = engine()
+
+    if action == "list":
+        try:
+            records = _figure_records(eng.dsh_figure_info(nargout=1), "dsh_figure_info")
+        except Exception as exc:  # noqa: BLE001
+            return {"ok": False, "err": str(exc)}
+        return {"ok": True, "figures": [_figure_record(entry) for entry in records]}
+
+    if action == "save":
+        which = int(req.get("figure") or 0)
+        directory = str(req.get("dir") or os.path.join(os.getcwd(), ".matlab-figures"))
+        try:
+            records = _figure_records(
+                eng.dsh_figure_save(directory, float(which), nargout=1), "dsh_figure_save"
+            )
+        except Exception as exc:  # noqa: BLE001
+            return {"ok": False, "err": str(exc)}
+        return {
+            "ok": True,
+            "dir": directory,
+            "figures": [_figure_record(entry) for entry in records],
+        }
+
+    if action == "close":
+        which = int(req.get("figure") or 0)
+        command = "close all" if which == 0 else "close %d" % which
+        out, err = control(command)
+        return {"ok": err == "", "out": out, "err": err}
+
+    # Unreachable: the action was validated at the top of this function.
+    return {"ok": False, "err": "unknown figure action: %s" % action}
+
+
+def dispatch(req):
+    global _engine
+    op = req.get("op", "")
+    if op == "ping":
+        return {"ok": True, "engineRunning": _engine is not None}
+    if op == "start":
+        eng = engine()
+        version = eng.eval("version", nargout=1)
+        return {"ok": True, "version": str(version)}
+    if op == "eval":
+        return op_eval(req)
+    if op == "debug":
+        return op_debug(req)
+    if op == "figure":
+        return op_figure(req)
+    if op == "shutdown":
+        if _engine is not None:
+            try:
+                _engine.quit()
+            except Exception:  # noqa: BLE001
+                pass
+            _engine = None
+        emit({"id": req.get("id"), "ok": True, "state": "shutdown"})
+        raise SystemExit(0)
+    return {"ok": False, "err": "unknown op: %s" % op}
+
+
+def main():
+    for raw in _STDIN:
+        line = raw.decode("utf-8-sig", "replace").strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except Exception as exc:  # noqa: BLE001
+            emit({"id": None, "ok": False, "err": "bad request json: %s" % exc})
+            continue
+        try:
+            response = dispatch(req)
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            response = {"ok": False, "err": "%s: %s" % (type(exc).__name__, exc)}
+        response["id"] = req.get("id")
+        emit(response)
+
+
+if __name__ == "__main__":
+    main()

package/python/selftest.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Self-test for the MATLAB bridge driver.
+
+Exercises the JSON-lines protocol end to end against a real MATLAB session:
+engine startup, base-workspace output capture, error reporting, figure export,
+and the full breakpoint stepping sequence. Run this after touching ml_driver.py,
+dsh_evalbase.m or the dsh_figure_* helpers -- a failure here is unambiguously a
+driver bug rather than a Cordis plugin or transport bug.
+
+    python selftest.py            # run everything
+    python selftest.py --no-debug # skip the MATLAB-starting debug half
+
+Exits 0 when every check passes, 1 otherwise.
+"""
+
+import argparse
+import itertools
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DRIVER = os.path.join(HERE, "ml_driver.py")
+PYLIBS = os.path.join(HERE, "pylibs")
+PYEXE = sys.executable
+
+FIXTURE = """function result = bridge_fixture()
+  a = 1;
+  b = 2;
+  c = a + b;
+  d = c * 10;
+  result = d;
+end
+"""
+
+failures = []
+
+
+def check(label, condition, detail=""):
+    status = "PASS" if condition else "FAIL"
+    print("[%s] %s%s" % (status, label, (" -- " + detail) if detail else ""), flush=True)
+    if not condition:
+        failures.append(label)
+
+
+class Driver:
+    def __init__(self):
+        env = dict(os.environ)
+        env["PYTHONPATH"] = PYLIBS
+        env["PYTHONIOENCODING"] = "utf-8"
+        self.proc = subprocess.Popen(
+            [PYEXE, "-u", DRIVER],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            env=env,
+        )
+        self.ids = itertools.count(1)
+        self.chatter = []
+
+    def call(self, op, **kw):
+        req = {"id": next(self.ids), "op": op}
+        req.update(kw)
+        self.proc.stdin.write(json.dumps(req) + "\n")
+        self.proc.stdin.flush()
+        while True:
+            line = self.proc.stdout.readline()
+            if not line:
+                raise RuntimeError("driver died while waiting for %r" % op)
+            if line.startswith("@@DSH:"):
+                return json.loads(line[len("@@DSH:"):])
+            self.chatter.append(line.rstrip())
+
+    def close(self):
+        try:
+            self.call("shutdown")
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            self.proc.wait(timeout=30)
+        except Exception:  # noqa: BLE001
+            self.proc.kill()
+
+
+def run_eval_checks(driver):
+    started = time.time()
+    resp = driver.call("start")
+    check("engine starts", resp.get("ok") is True, "version=%s" % resp.get("version"))
+    print("    engine start took %.1fs" % (time.time() - started), flush=True)
+
+    resp = driver.call("eval", code="x = 41")
+    out = resp.get("out", "")
+    # MATLAB's display puts a newline between `x =` and the value, so compare on
+    # collapsed whitespace rather than against a contiguous "x = 41".
+    check("assignment echoes like the command window", "x = 41" in " ".join(out.split()), repr(out))
+
+    resp = driver.call("eval", code="x + 1")
+    out = resp.get("out", "")
+    check("bare expression echoes ans", "ans" in out and "42" in out, repr(out))
+    check("bare expression is not echoed twice", out.count("42") == 1, repr(out))
+
+    resp = driver.call("eval", code="disp('hello');\ny = x * 2;\nfprintf('y=%d\\n', y);")
+    check("multi-line output captured", "hello" in resp.get("out", "") and "y=82" in resp.get("out", ""), repr(resp.get("out")))
+
+    resp = driver.call("eval", code="disp('hi')")
+    check("output-less call does not error", resp.get("ok") is True and resp.get("out", "").strip() == "hi", repr(resp))
+
+    resp = driver.call("eval", code="format short")
+    check("command syntax is not treated as an expression", resp.get("ok") is True, repr(resp))
+
+    resp = driver.call("eval", code="no_such_function_here(3)")
+    check("error is reported", resp.get("ok") is False and resp.get("err"), repr(resp.get("err")))
+    check("error carries a stack", bool(resp.get("stack")), repr(resp.get("stack")))
+
+    resp = driver.call("eval", code="x")
+    check("state persists across calls", "41" in resp.get("out", ""), repr(resp.get("out")))
+
+
+def run_figure_checks(driver, out_dir):
+    resp = driver.call(
+        "eval",
+        code="close all\nfigure('Visible','off')\nplot(1:5, [1 4 9 16 25], 'o-')\ntitle('selftest')\n",
+    )
+    check("a plot can be created", resp.get("ok") is True, repr(resp.get("err")))
+
+    resp = driver.call("figure", action="list")
+    figures = resp.get("figures", [])
+    check("figure list finds the open figure", resp.get("ok") is True and len(figures) == 1, repr(resp))
+
+    resp = driver.call("figure", action="save", dir=out_dir)
+    figures = resp.get("figures", [])
+    check("figure save reports one path", resp.get("ok") is True and len(figures) == 1, repr(resp))
+
+    path = figures[0].get("path") if figures else None
+    check("saved figure has no error", bool(figures) and figures[0].get("error") == "", repr(figures))
+    check("exported PNG exists", bool(path) and os.path.isfile(path), repr(path))
+    size = os.path.getsize(path) if path and os.path.isfile(path) else 0
+    check("exported PNG is not empty", size > 1000, "%d bytes" % size)
+
+    magic = b""
+    if path and os.path.isfile(path):
+        with open(path, "rb") as handle:
+            magic = handle.read(8)
+    check("exported file is a real PNG", magic == b"\x89PNG\r\n\x1a\n", repr(magic))
+
+    resp = driver.call("figure", action="save", figure=99, dir=out_dir)
+    check("saving a nonexistent figure is not an error",
+          resp.get("ok") is True and resp.get("figures") == [], repr(resp))
+
+    resp = driver.call("figure", action="close")
+    check("close succeeds", resp.get("ok") is True, repr(resp))
+
+    resp = driver.call("figure", action="list")
+    check("no figures remain after close", resp.get("ok") is True and resp.get("figures") == [], repr(resp))
+
+    resp = driver.call("figure", action="nonsense")
+    check("an invalid figure action is rejected", resp.get("ok") is False, repr(resp))
+
+
+def run_debug_checks(driver, fixture_dir):
+    driver.call("eval", code="addpath('%s')" % fixture_dir.replace("\\", "\\\\"))
+
+    resp = driver.call("debug", action="break", file="bridge_fixture", line=4)
+    check("breakpoint is set", resp.get("ok") is True, repr(resp))
+
+    resp = driver.call("debug", action="run", code="bridge_fixture", waitMs=15000)
+    check("run pauses at the breakpoint", resp.get("state") == "paused", repr(resp.get("state")))
+
+    resp = driver.call("debug", action="status")
+    check("status reports paused", resp.get("paused") is True, repr(resp))
+
+    resp = driver.call("debug", action="vars")
+    out = resp.get("out", "")
+    check("paused frame exposes locals", "a" in out and "b" in out, repr(out))
+
+    resp = driver.call("debug", action="get", name="a")
+    check("reads a local by name", resp.get("ok") is True and resp.get("out", "").startswith("1"), repr(resp))
+
+    resp = driver.call("debug", action="get", name="c")
+    check("unassigned local is reported as an error", resp.get("ok") is False, repr(resp))
+
+    resp = driver.call("debug", action="step")
+    check("step keeps the session paused", resp.get("state") == "paused", repr(resp.get("state")))
+
+    resp = driver.call("debug", action="get", name="c")
+    check("stepping makes the next local visible", resp.get("ok") is True and resp.get("out", "").startswith("3"), repr(resp))
+
+    resp = driver.call("debug", action="eval", code="a + b")
+    check("evaluates an expression in the paused frame", resp.get("ok") is True and resp.get("out", "").startswith("3"), repr(resp))
+
+    resp = driver.call("debug", action="stack")
+    check("stack is available while paused", resp.get("ok") is True and bool(resp.get("out")), repr(resp.get("out")))
+
+    resp = driver.call("debug", action="continue")
+    check("continue completes the run", resp.get("state") == "completed", repr(resp))
+
+    resp = driver.call("debug", action="status")
+    check("status reports not paused after continue", resp.get("paused") is False, repr(resp))
+
+    resp = driver.call("debug", action="step")
+    check("stepping outside a pause is refused cleanly", resp.get("ok") is False, repr(resp))
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--no-debug", action="store_true", help="skip checks that start MATLAB")
+    args = parser.parse_args()
+
+    if not os.path.isdir(PYLIBS):
+        print("engine libs missing at %s -- run setup_engine.ps1 first" % PYLIBS, flush=True)
+        return 1
+
+    with tempfile.TemporaryDirectory(prefix="dsh-matlab-selftest-") as tmp:
+        with open(os.path.join(tmp, "bridge_fixture.m"), "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(FIXTURE)
+
+        driver = Driver()
+        try:
+            resp = driver.call("ping")
+            check("driver answers ping", resp.get("ok") is True, repr(resp))
+            check("engine is lazy before first use", resp.get("engineRunning") is False, repr(resp))
+
+            run_eval_checks(driver)
+            run_figure_checks(driver, tmp)
+            if not args.no_debug:
+                run_debug_checks(driver, tmp)
+        finally:
+            driver.close()
+
+    print(flush=True)
+    if failures:
+        print("SELFTEST FAILED: %d check(s): %s" % (len(failures), ", ".join(failures)), flush=True)
+        return 1
+    print("SELFTEST PASSED", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())