@alotop/dsh-matlab-bridge 0.1.1 → 0.1.6

package/README.md

@@ -206,8 +206,8 @@ such as `disp('hi')`.
 ## Development
 
 ```sh
-git clone https://github.com/alotop/dsh-matlab-bridge.git
-cd dsh-matlab-bridge
+git clone https://github.com/alotop/dsh-matlab.git
+cd dsh-matlab
 npm run setup      # lay out the engine runtime from your local MATLAB
 npm run selftest   # end-to-end checks against a real MATLAB (starts one)
 npm run check      # syntax-check the plugin and scripts
@@ -235,7 +235,7 @@ repository. One-time setup on npmjs.com:
 
 1. The package must exist — do a first manual `npm publish` from a checkout.
 2. Package → Settings → **Trusted Publisher** → GitHub Actions, with
-   repository `alotop/dsh-matlab-bridge` and workflow `release.yml`.
+   repository `alotop/dsh-matlab` and workflow `release.yml`.
 
 After that, `id-token: write` in the workflow is the only credential needed, and
 every published version carries a signed provenance attestation.

package/README.zh-CN.md

@@ -156,8 +156,8 @@ MATLAB Engine 会把 MATLAB 命令窗口输出转发到驱动的 stdout，裸 JS
 ## 开发
 
 ```sh
-git clone https://github.com/alotop/dsh-matlab-bridge.git
-cd dsh-matlab-bridge
+git clone https://github.com/alotop/dsh-matlab.git
+cd dsh-matlab
 npm run setup      # 从本地 MATLAB 铺开引擎运行库
 npm run selftest   # 对真实 MATLAB 的端到端检查（会启动一个）
 npm run check      # 语法检查插件与脚本

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@alotop/dsh-matlab-bridge",
-  "version": "0.1.1",
+  "version": "0.1.6",
   "description": "Run and interactively debug MATLAB code from a DSH session, through a persistent MATLAB Engine session.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alotop/dsh-matlab.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -36,23 +44,16 @@
   "scripts": {
     "setup": "node scripts/setup-engine.mjs",
     "selftest": "node scripts/run-selftest.mjs",
-    "check": "node --check src/plugin.mjs && node --check scripts/setup-engine.mjs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/alotop/dsh-matlab-bridge.git"
+    "check": "node --check src/plugin.mjs && node --check scripts/setup-engine.mjs && node --check scripts/run-selftest.mjs && node --check scripts/inspect-tarball.mjs",
+    "pack:check": "npm pack --dry-run --json > pack.json && node scripts/inspect-tarball.mjs"
   },
   "bugs": {
-    "url": "https://github.com/alotop/dsh-matlab-bridge/issues"
+    "url": "https://github.com/alotop/dsh-matlab/issues"
   },
-  "homepage": "https://github.com/alotop/dsh-matlab-bridge#readme",
+  "homepage": "https://github.com/alotop/dsh-matlab#readme",
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     }
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
   }
 }

package/python/ml_driver.py

@@ -70,6 +70,14 @@ _STDOUT = sys.stdout.buffer
 
 PROTOCOL_PREFIX = "@@DSH:"
 
+# Every action op_debug implements. Kept here so an unknown action can be
+# rejected before the engine is touched -- see op_debug.
+DEBUG_ACTIONS = (
+    "break", "breakError", "clearBreaks", "run", "status", "stack",
+    "vars", "get", "eval", "step", "stepIn", "stepOut", "continue",
+    "quit", "finish",
+)
+
 _engine = None
 _future = None
 _last_run_error = None
@@ -172,6 +180,11 @@ def op_eval(req):
 def op_debug(req):
     global _future, _last_run_error
     action = req.get("action", "")
+    # Validate before touching the engine: a typo must not pay a ~20s MATLAB
+    # launch, which is otherwise a very expensive way to learn you misspelled
+    # an action.
+    if action not in DEBUG_ACTIONS:
+        return {"ok": False, "err": "unknown debug action: %s" % action}
     eng = engine()
 
     if action == "break":
@@ -277,18 +290,23 @@ def op_debug(req):
 
 
 def _format_value(value):
-    """Render a MATLAB value for the model without dumping it as Python repr."""
+    """Render a MATLAB value as text for the model.
+
+    Formatting happens in Python because that is where the value already lives.
+    Calling back into MATLAB with `evalc('disp(value)')` would name a MATLAB
+    variable `value` that does not exist, so it merely leaked a spurious
+    "unrecognized function or variable 'value'" onto stderr beside a value that
+    was on its way out anyway. Engine array wrappers stringify to a readable
+    nested list, which is a fine rendering for a debugger readout.
+    """
     if value is None:
         return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
     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)
+        # MATLAB prints an integral double without a trailing ".0".
+        return str(int(value)) if value.is_integer() else repr(value)
+    return str(value)
 
 
 def _load_json(payload, label):

package/python/selftest.py

@@ -157,9 +157,8 @@ def run_figure_checks(driver, out_dir):
 
     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))
+    # Rejecting an unknown action is asserted in main(), before MATLAB starts,
+    # so that the same check also proves a typo does not launch the engine.
 
 
 def run_debug_checks(driver, fixture_dir):
@@ -179,7 +178,7 @@ def run_debug_checks(driver, fixture_dir):
     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))
+    check("reads a local by name", resp.get("ok") is True and resp.get("out", "").strip() == "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))
@@ -188,10 +187,20 @@ def run_debug_checks(driver, fixture_dir):
     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))
+    check("stepping makes the next local visible", resp.get("ok") is True and resp.get("out", "").strip() == "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))
+    check("evaluates an expression in the paused frame", resp.get("ok") is True and resp.get("out", "").strip() == "3", repr(resp))
+
+    # Regression: _format_value once called back into MATLAB with an expression
+    # naming `value`, which is a PYTHON variable -- MATLAB has no such name, so
+    # every non-scalar readout leaked an error onto stderr beside its value.
+    before = len(driver.chatter)
+    resp = driver.call("debug", action="eval", code="[a b]")
+    leaked = driver.chatter[before:]
+    check("evaluating a vector in the paused frame succeeds", resp.get("ok") is True, repr(resp))
+    check("a frame value readout leaks no MATLAB error to stderr",
+          not any("value" in line for line in leaked), repr(leaked))
 
     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")))
@@ -225,6 +234,16 @@ def main():
             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))
 
+            # Rejecting an unknown action must not pay a MATLAB launch. These
+            # run before any check that starts the engine, so "still lazy" is a
+            # meaningful assertion rather than a restatement of "already up".
+            resp = driver.call("debug", action="nonsense")
+            check("an invalid debug action is rejected", resp.get("ok") is False, repr(resp))
+            resp = driver.call("figure", action="nonsense")
+            check("an invalid figure action is rejected", resp.get("ok") is False, repr(resp))
+            resp = driver.call("ping")
+            check("a rejected action does not launch MATLAB", resp.get("engineRunning") is False, repr(resp))
+
             run_eval_checks(driver)
             run_figure_checks(driver, tmp)
             if not args.no_debug:

package/scripts/inspect-tarball.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Validate what `npm pack` is about to publish.
+ *
+ * Reads the JSON that `npm pack --dry-run --json` writes to pack.json, so the
+ * assertions live in one file instead of being duplicated as inline `node -e`
+ * snippets in ci.yml and release.yml.
+ *
+ * WHY NOT AN INLINE `node -e`
+ * This package is `"type": "module"`, and a recent Node 22.x began evaluating
+ * `-e` input according to that field. Under ESM there is no `require`, so the
+ * previous inline version died with "require is not a function" -- on CI but
+ * not on the older Node used locally, which is the worst way for a check to
+ * fail. A script file has an unambiguous module type and needs no shell
+ * quoting either.
+ *
+ * WHY THE OUTPUT SHAPE IS NORMALIZED
+ * `npm pack --json` changed shape without a major-version signal in the CLI:
+ *
+ *   npm <= 11   [ { name, entryCount, files: [{ path, size, mode }] } ]
+ *   npm >= 12   { "<name>": { name, entryCount, files: [...] } }
+ *
+ * npm 12 passes `key: tar.name` to its logger, which wraps the record in an
+ * object keyed by package name (lib/utils/tar.js). A check that only handled
+ * the array form passed locally and failed on CI, which installs npm@latest.
+ * findPackRecord() accepts either, and the failure path prints the keys it did
+ * see so the next shape change is diagnosable from one CI log rather than a
+ * source-reading session.
+ *
+ *   npm pack --dry-run --json > pack.json
+ *   node scripts/inspect-tarball.mjs
+ */
+
+import { readFileSync } from 'node:fs'
+import process from 'node:process'
+
+/**
+ * Files the runtime needs at run time. A `files` entry that drops one of these
+ * installs cleanly and then fails in the user's session, which is exactly the
+ * regression this list exists to catch.
+ */
+const REQUIRED_FILES = [
+  'src/plugin.mjs',
+  'cordis.patch.yml',
+  'python/ml_driver.py',
+  'python/mfiles/dsh_evalbase.m',
+  'python/mfiles/dsh_figure_info.m',
+  'python/mfiles/dsh_figure_save.m',
+  'scripts/setup-engine.mjs',
+]
+
+/** Find the package record inside either the array or the keyed-object shape. */
+function findPackRecord(pack) {
+  const hasFiles = (value) => value !== null && typeof value === 'object' && Array.isArray(value.files)
+  if (Array.isArray(pack)) return pack.find(hasFiles) ?? pack[0]
+  if (pack !== null && typeof pack === 'object') {
+    if (hasFiles(pack)) return pack
+    return Object.values(pack).find(hasFiles)
+  }
+  return undefined
+}
+
+let pack
+try {
+  pack = JSON.parse(readFileSync('pack.json', 'utf8'))
+} catch (error) {
+  console.error('error: could not read pack.json')
+  console.error('       run `npm pack --dry-run --json > pack.json` first')
+  console.error('       ' + String((error && error.message) || error))
+  process.exit(1)
+}
+
+const entry = findPackRecord(pack)
+if (entry === undefined) {
+  console.error('error: no package record with a file list in pack.json')
+  console.error('       top-level: ' + (Array.isArray(pack) ? 'array' : typeof pack))
+  const keys = Array.isArray(pack) ? Object.keys(pack[0] ?? {}) : Object.keys(pack ?? {})
+  console.error('       keys seen: ' + JSON.stringify(keys))
+  process.exit(1)
+}
+
+const paths = entry.files.map((file) => (typeof file === 'string' ? file : file.path))
+const failures = []
+
+// The engine runtime is MathWorks code laid out from the user's own MATLAB
+// installation. Redistributing it through the registry would be a licence
+// problem, so this is a hard stop rather than a warning.
+const leaked = paths.filter((path) => typeof path === 'string' && path.includes('pylibs'))
+if (leaked.length > 0) {
+  failures.push('engine runtime must not be published: ' + leaked.join(', '))
+}
+
+const missing = REQUIRED_FILES.filter((path) => !paths.includes(path))
+if (missing.length > 0) {
+  failures.push('package is missing required files: ' + missing.join(', '))
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) console.error('error: ' + failure)
+  process.exit(1)
+}
+
+const fileCount = entry.entryCount ?? paths.length
+const sizeKb = Math.round((entry.size ?? 0) / 1024)
+console.log('tarball ok: ' + fileCount + ' files, ' + sizeKb + ' kB, no engine runtime')