@alotop/dsh-matlab-bridge 0.1.1

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 alotop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package does not redistribute any MathWorks code. The MATLAB Engine for
+Python runtime is laid out at install time by `scripts/setup-engine.mjs`, which
+copies it out of a MATLAB installation the user already has and is licensed to
+use. That generated copy lives in `python/pylibs/` and is neither committed to
+this repository nor published to npm.

package/README.md

@@ -0,0 +1,263 @@
+# @alotop/dsh-matlab-bridge
+
+Run and interactively debug MATLAB code from a [DSH](https://github.com/deepseek-ai) session,
+through a persistent MATLAB Engine session.
+
+[![npm](https://img.shields.io/npm/v/@alotop/dsh-matlab-bridge.svg)](https://www.npmjs.com/package/@alotop/dsh-matlab-bridge)
+[![license](https://img.shields.io/npm/l/@alotop/dsh-matlab-bridge.svg)](LICENSE)
+
+[中文文档](README.zh-CN.md)
+
+---
+
+## Why this exists
+
+MATLAB cannot start under DSH's default `workspace-write` file sandbox. It writes
+outside the workspace during startup (preferences, licence cache) and dies with:
+
+```
+Fatal Startup Error: System error: File system inconsistency
+```
+
+Relocating its preference directory does not help. Driving `matlab -batch`
+through a shell therefore costs one sandbox escalation **per call**.
+
+This plugin spawns its driver through the unconfined `ctx.subprocess` seam
+instead, so that cost is paid once — and it keeps a MATLAB Engine session alive,
+which is what makes debugging possible at all.
+
+### Why a persistent session, not `matlab -batch`
+
+`matlab -batch` pays a ~20 second cold start on every call and keeps nothing: no
+variables, no open figures, no breakpoints. It also **cannot single-step**,
+because a breakpoint blocks MATLAB's own command loop. Stepping needs an
+out-of-band evaluator, which is exactly what the official MATLAB Engine API
+provides.
+
+```
+DSH session ──ctx.subprocess.spawn──▶ python ml_driver.py
+                                       │ matlab.engine
+                                       ▼
+                              persistent, debuggable MATLAB
+```
+
+## Requirements
+
+| | |
+|---|---|
+| MATLAB | R2020a or newer (for `exportgraphics`). Any standard install — the Python engine under `extern/engines/python` is what this uses. |
+| Python | 3.9 – 3.13 on `PATH` |
+| Node.js | 20 or newer |
+
+The bundled engine advertises Python 3.9–3.12, but it ships a stable-ABI
+(`abi3`) extension module that loads and runs correctly on 3.13 as well.
+
+## Install
+
+```sh
+# 1. install the package into your DSH profile
+dsh plugin --profile <profile> add @alotop/dsh-matlab-bridge
+
+# 2. lay out the MATLAB Engine runtime inside that installed copy
+node "<profile>/node_modules/@alotop/dsh-matlab-bridge/scripts/setup-engine.mjs"
+
+# 3. restart DSH so the new bundle layer is composed
+```
+
+Step 2 copies the engine out of the MATLAB you already have and generates the
+`_arch.txt` file the engine needs to find MATLAB's native libraries. Nothing is
+downloaded, and no MathWorks code is redistributed — see [LICENSE](LICENSE).
+
+**Run step 2 against the installed copy, not a checkout.** The script writes to
+`python/pylibs` beside itself, and the plugin loads the runtime from its own
+installation — laying it out anywhere else leaves the installed copy empty. The
+same copy also exposes the command as
+`<profile>/node_modules/.bin/dsh-matlab-bridge-setup`.
+
+### Why `dsh.bundle` is declared
+
+`dsh plugin add` records a package as a **profile layer** only when its
+`package.json` declares `dsh.bundle`. This package points that at
+[`cordis.patch.yml`](cordis.patch.yml), which inserts the `matlab-bridge` row.
+Without it the install still succeeds but nothing is registered, and DSH says so:
+*declares no dsh.bundle — installed as a plain dependency, not a profile layer*.
+
+### Alternative: a preset row
+
+The same plugin can be composed from an agent preset instead of a profile
+bundle. The row publishes no service and registers tools only, so it sits at the
+top level of a preset and needs no `isolate` realm.
+
+```yaml
+- id: matlab-bridge
+  name: '@alotop/dsh-matlab-bridge'
+```
+
+### Standalone, or from a checkout
+
+For developing the bridge itself, or before it is on npm:
+
+```sh
+npm pack                                                       # -> alotop-dsh-matlab-bridge-<version>.tgz
+npx ./alotop-dsh-matlab-bridge-<version>.tgz                   # run setup straight from the tarball
+npm install -g ./alotop-dsh-matlab-bridge-<version>.tgz        # or install it globally
+npm install --no-save ./alotop-dsh-matlab-bridge-<version>.tgz # or into a project
+```
+
+Pass `--no-save` when you only want to try the tarball; without it npm records a
+`file:` dependency on the tarball in that project's `package.json`.
+
+There is only **one** package. `dsh-matlab-bridge-setup` is a `bin` entry of it,
+not a separate package — `npx @alotop/dsh-matlab-bridge` resolves to that
+executable because it is the package's only one.
+
+### Row options
+
+All optional; the defaults need no configuration on a normal machine.
+
+```yaml
+- id: matlab-bridge
+  name: '@alotop/dsh-matlab-bridge'
+  config:
+    pythonPath: python3.12        # default: first of python3, python on PATH
+    workDir: /path/to/project     # default: the calling session's cwd
+    figureDir: /tmp/figures       # default: <workDir>/.matlab-figures
+    timeoutMs: 180000             # default: 180000
+```
+
+## Tools
+
+### `matlab_run`
+
+Runs MATLAB code in the persistent session and returns its command-window
+output. **Variables, figures and loaded data persist across calls.** Print with
+`disp`/`fprintf`, or pass a single bare expression to have its value shown. On
+failure the MATLAB error message and error stack come back.
+
+```
+matlab_run: A = magic(4); disp(trace(A))
+```
+
+### `matlab_debug`
+
+Drives the MATLAB debugger. Actions: `break`, `breakError`, `clearBreaks`,
+`run`, `status`, `stack`, `vars`, `get`, `eval`, `step`, `stepIn`, `stepOut`,
+`continue`, `quit`, `finish`.
+
+A worked session:
+
+```
+matlab_debug action=break file=myfunc line=12   → ok
+matlab_debug action=run   code="myfunc(data)"   → state: paused
+matlab_debug action=vars                        → the paused frame's locals
+matlab_debug action=get   name=startIndex       → 7
+matlab_debug action=eval  code="n - k + 1"      → 8
+matlab_debug action=step                        → state: paused (next line)
+matlab_debug action=continue                    → state: completed
+```
+
+`eval` runs an expression inside the paused frame, so a hypothesis about a live
+local can be confirmed without editing the file. A breakpoint on a comment or
+blank line binds to the next executable line, exactly as in the MATLAB editor.
+
+### `matlab_figure`
+
+Inspects and exports figures. `list` reports open figures, `save` writes each
+one to a 150 DPI PNG and returns the paths, `close` closes one or all.
+
+Plot first with `matlab_run`, export afterwards — figures stay open in the
+session. **Read the exported PNGs back with `read_image`;** a path alone shows
+nothing.
+
+### `matlab_session`
+
+`start`, `status`, `stop`. MATLAB takes tens of seconds to start, so the session
+stays warm and is reused. `status` reports the package path, whether the driver
+is running, and whether the engine runtime has been laid out.
+
+## How it works
+
+| File | Role |
+|---|---|
+| `src/plugin.mjs` | The Cordis plugin: locates its own files, owns the driver process, registers the tools |
+| `python/ml_driver.py` | Persistent driver. Newline-delimited JSON on stdin/stdout, owning one MATLAB Engine session |
+| `python/mfiles/dsh_evalbase.m` | Evaluates in the base workspace and reproduces command-window echo semantics |
+| `python/mfiles/dsh_figure_*.m` | List and export figures as JSON |
+| `scripts/setup-engine.mjs` | Lays out the engine runtime from a local MATLAB |
+| `python/selftest.py` | End-to-end self-test against a real MATLAB |
+
+### The `@@DSH:` protocol prefix
+
+The MATLAB Engine forwards the MATLAB command window to the driver's stdout, so
+a bare JSON protocol would race with MATLAB's own output. Every protocol line is
+prefixed with `@@DSH:`; every unprefixed line is MATLAB chatter and is surfaced
+as diagnostics rather than parsed.
+
+### Command-window echo semantics
+
+`dsh_evalbase.m` calls `evalc('evalin(''base'', code)')` and deliberately asks
+`evalin` for **no output argument**. That is what makes capture match the command
+window: an assignment echoes `x = 41`, a bare expression echoes `ans = 42`, and a
+statement with no value prints nothing. Asking for an output argument suppresses
+all three, and guessing from the source text whether the code is an expression
+misclassifies command syntax such as `dbstop in f at 4` and output-less calls
+such as `disp('hi')`.
+
+## Development
+
+```sh
+git clone https://github.com/alotop/dsh-matlab-bridge.git
+cd dsh-matlab-bridge
+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
+```
+
+`npm run selftest` exercises the protocol, output capture, error reporting,
+figure export and the full breakpoint stepping sequence. A failure there is a
+driver bug, not a plugin or transport bug, which keeps the fault domain small.
+
+## Releasing
+
+Publishing runs only on a version tag, and only
+[`.github/workflows/release.yml`](.github/workflows/release.yml) can do it:
+
+```sh
+npm version patch        # or minor / major; commits and tags
+git push --follow-tags
+```
+
+The workflow refuses to publish when the tag and `package.json` version
+disagree, and refuses to publish a tarball containing the engine runtime.
+
+Authentication is **OIDC Trusted Publishing**, so no npm token is stored in the
+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`.
+
+After that, `id-token: write` in the workflow is the only credential needed, and
+every published version carries a signed provenance attestation.
+
+## Limitations
+
+- **Figures are delivered as files, not inline images.** `matlab_figure` returns
+  PNG paths. An inline image block would have to go through the attachments
+  service to obtain an attachment reference; a path plus `read_image` already
+  makes the plot visible and carries no service-contract dependency.
+- **A hard-killed driver can leave MATLAB behind.** The driver quits the engine
+  on `atexit`, which does not run on a hard kill. Use `matlab_session` with
+  `action="stop"` to shut down cleanly.
+- **Queries queue while MATLAB is busy.** The engine serializes requests on one
+  thread, so a `dbstack` probe issued while a background run is mid-execution
+  blocks until that run yields. `run` checks completion before probing the stack
+  to avoid the worst of it.
+- **Single-step debugging is Windows-verified.** The engine layout logic handles
+  `glnxa64` and `maca64`/`maci64`, but only Windows has been exercised
+  end-to-end. Reports from other platforms are welcome.
+
+## License
+
+[MIT](LICENSE). This package does not redistribute MathWorks code; see the note
+at the end of the license file.

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# @alotop/dsh-matlab-bridge
+
+在 [DSH](https://github.com/deepseek-ai) 会话里**运行和交互式单步调试** MATLAB 代码，底层是一个常驻的 MATLAB Engine 会话。
+
+[![npm](https://img.shields.io/npm/v/@alotop/dsh-matlab-bridge.svg)](https://www.npmjs.com/package/@alotop/dsh-matlab-bridge)
+[![license](https://img.shields.io/npm/l/@alotop/dsh-matlab-bridge.svg)](LICENSE)
+
+[English](README.md)
+
+---
+
+## 为什么需要它
+
+MATLAB 在 DSH 默认的 `workspace-write` 文件沙箱下**根本无法启动**。它在启动时会写工作区之外的位置（偏好设置、许可缓存），然后直接崩掉：
+
+```
+Fatal Startup Error: System error: File system inconsistency
+```
+
+把偏好目录重定向到可写位置**也没用**。所以用 shell 去驱动 `matlab -batch`，代价是**每一次调用都要一次沙箱提权**。
+
+本插件改为通过非受限的 `ctx.subprocess` 通道启动驱动进程，这笔代价只需付一次——而且它保持一个 MATLAB Engine 会话存活，这正是一切调试能力的前提。
+
+### 为什么必须常驻会话，而不是 `matlab -batch`
+
+`matlab -batch` 每次调用都要**约 20 秒冷启动**，而且什么都不保留：变量、打开的图形、断点全部丢失。更关键的是它**无法单步调试**——断点命中时 MATLAB 自己的命令循环被阻塞，要发出 `dbstep` 必须有带外求值器，而官方 MATLAB Engine API 提供的正是这个。
+
+```
+DSH 会话 ──ctx.subprocess.spawn──▶ python ml_driver.py
+                                    │ matlab.engine
+                                    ▼
+                          常驻、可调试的 MATLAB
+```
+
+## 环境要求
+
+| | |
+|---|---|
+| MATLAB | R2020a 或更新（需要 `exportgraphics`）。任意标准安装即可，用的是它自带的 `extern/engines/python`。 |
+| Python | 3.9 – 3.13，需在 `PATH` 上 |
+| Node.js | 20 或更新 |
+
+引擎自带的声明是支持 Python 3.9–3.12，但它附带的是**稳定 ABI（`abi3`）**扩展模块，实测在 3.13 上也能正常装载和运行。
+
+## 安装
+
+```sh
+# 1. 把包装进你的 DSH profile
+dsh plugin --profile <profile> add @alotop/dsh-matlab-bridge
+
+# 2. 在「已安装的那份」里铺开 Engine 运行库
+node "<profile>/node_modules/@alotop/dsh-matlab-bridge/scripts/setup-engine.mjs"
+
+# 3. 重启 DSH，让新的 bundle 层被组装进去
+```
+
+第 2 步会从你**已经装好的** MATLAB 里复制引擎，并生成引擎定位原生库所需的 `_arch.txt`。不下载任何东西，也不再分发任何 MathWorks 代码——详见 [LICENSE](LICENSE)。
+
+**第 2 步必须针对「已安装的那份」执行，不要跑仓库里的检出。** 脚本会写到它自己旁边的 `python/pylibs`，而插件是从自己的安装位置加载运行库的——铺到别处，已安装的那份仍然是空的。同一份安装也提供 `<profile>/node_modules/.bin/dsh-matlab-bridge-setup` 这个命令。
+
+### 为什么要声明 `dsh.bundle`
+
+`dsh plugin add` 只有在包的 `package.json` 声明了 `dsh.bundle` 时，才会把它记为 **profile layer**。本包把它指向 [`cordis.patch.yml`](cordis.patch.yml)，由后者插入 `matlab-bridge` 这一行。没有它，安装照样成功但**什么都不会注册**，DSH 也会明确提示：*declares no dsh.bundle — installed as a plain dependency, not a profile layer*。
+
+### 备选：写成 preset 行
+
+同一个插件也可以不用 profile bundle，而是从 agent preset 组装。该行只注册工具、不发布服务，因此直接放在 preset 顶层即可，不需要 `isolate` realm。
+
+```yaml
+- id: matlab-bridge
+  name: '@alotop/dsh-matlab-bridge'
+```
+
+### 独立使用，或从检出安装
+
+用于开发这个桥接本身，或者包还没发到 npm 之前：
+
+```sh
+npm pack                                                       # 得到 alotop-dsh-matlab-bridge-<版本>.tgz
+npx ./alotop-dsh-matlab-bridge-<版本>.tgz                      # 直接从 tarball 跑安装命令
+npm install -g ./alotop-dsh-matlab-bridge-<版本>.tgz           # 或全局安装
+npm install --no-save ./alotop-dsh-matlab-bridge-<版本>.tgz    # 或装进某个工程
+```
+
+只想试一下 tarball 时记得加 `--no-save`；否则 npm 会在那个工程的 `package.json` 里记下一条指向 tarball 的 `file:` 依赖。
+
+**只有一个包。** `dsh-matlab-bridge-setup` 是它的一个 `bin` 入口，不是独立包——`npx @alotop/dsh-matlab-bridge` 之所以能跑起它，是因为它是该包唯一的可执行文件。
+
+### 行配置
+
+全部可选，正常机器上无需任何配置。
+
+```yaml
+- id: matlab-bridge
+  name: '@alotop/dsh-matlab-bridge'
+  config:
+    pythonPath: python3.12        # 默认：PATH 上第一个 python3 / python
+    workDir: /path/to/project     # 默认：调用方会话的 cwd
+    figureDir: /tmp/figures       # 默认：<workDir>/.matlab-figures
+    timeoutMs: 180000             # 默认：180000
+```
+
+## 工具
+
+### `matlab_run`
+
+在常驻会话里运行 MATLAB 代码，返回命令窗口输出。**变量、图形、数据跨调用保留。** 用 `disp`/`fprintf` 打印，或者传入单个裸表达式让它显示值。失败时返回 MATLAB 错误信息与错误栈。
+
+### `matlab_debug`
+
+驱动 MATLAB 调试器。动作：`break`、`breakError`、`clearBreaks`、`run`、`status`、`stack`、`vars`、`get`、`eval`、`step`、`stepIn`、`stepOut`、`continue`、`quit`、`finish`。
+
+一次真实会话：
+
+```
+matlab_debug action=break file=myfunc line=12   → ok
+matlab_debug action=run   code="myfunc(data)"   → state: paused
+matlab_debug action=vars                        → 暂停帧的局部变量
+matlab_debug action=get   name=startIndex       → 7
+matlab_debug action=eval  code="n - k + 1"      → 8
+matlab_debug action=step                        → state: paused（下一行）
+matlab_debug action=continue                    → state: completed
+```
+
+`eval` 在**暂停帧内部**求值，所以可以在不改文件的前提下验证对某个活变量的推断。断点打在注释或空行上会绑定到下一个可执行行，与 MATLAB 编辑器行为一致。
+
+### `matlab_figure`
+
+检查与导出图形。`list` 列出打开的 figure，`save` 把每张图导出为 150 DPI 的 PNG 并返回路径，`close` 关闭一张或全部。
+
+先用 `matlab_run` 画图，再导出——figure 留在会话里。**拿到路径后要用 `read_image` 把 PNG 读回来**；只拿路径等于没看图。
+
+### `matlab_session`
+
+`start`、`status`、`stop`。MATLAB 启动要几十秒，所以会话保持热态并复用。`status` 会报告包路径、驱动是否在跑、以及引擎运行库是否已经铺开。
+
+## 工作原理
+
+| 文件 | 作用 |
+|---|---|
+| `src/plugin.mjs` | Cordis 插件：定位自身文件、持有驱动进程、注册工具 |
+| `python/ml_driver.py` | 常驻驱动。stdin/stdout 上是行分隔 JSON，持有一个 MATLAB Engine 会话 |
+| `python/mfiles/dsh_evalbase.m` | 在 base 工作区求值，复现命令窗口的回显语义 |
+| `python/mfiles/dsh_figure_*.m` | 以 JSON 形式列举与导出 figure |
+| `scripts/setup-engine.mjs` | 从本地 MATLAB 铺开引擎运行库 |
+| `python/selftest.py` | 对真实 MATLAB 的端到端自检 |
+
+### 为什么协议要带 `@@DSH:` 前缀
+
+MATLAB Engine 会把 MATLAB 命令窗口输出转发到驱动的 stdout，裸 JSON 协议会和这些输出抢同一个流。因此每一行协议都带 `@@DSH:` 前缀，不带前缀的行一律视为 MATLAB 输出（诊断信息），而不是去解析它。
+
+### 命令窗口回显语义
+
+`dsh_evalbase.m` 调用 `evalc('evalin(''base'', code)')`，并且**刻意不给 `evalin` 输出参数**。这才让捕获行为与命令窗口一致：赋值回显 `x = 41`，裸表达式回显 `ans = 42`，无值语句不输出。反过来，去要输出参数会把这三者全部抑制；而靠源码文本猜"是不是表达式"则会误判命令语法（如 `dbstop in f at 4`）和无输出参数的调用（如 `disp('hi')`）。
+
+## 开发
+
+```sh
+git clone https://github.com/alotop/dsh-matlab-bridge.git
+cd dsh-matlab-bridge
+npm run setup      # 从本地 MATLAB 铺开引擎运行库
+npm run selftest   # 对真实 MATLAB 的端到端检查（会启动一个）
+npm run check      # 语法检查插件与脚本
+```
+
+`npm run selftest` 覆盖协议、输出捕获、错误上报、图形导出，以及完整的断点单步链路。它失败 = 驱动有问题，而不是插件或传输层的问题，故障域因此很小。
+
+## 已知限制
+
+- **图形以文件交付，不是内联图像。** `matlab_figure` 返回 PNG 路径。工具结果理论上可以携带内联图像块，但那要走附件服务换取引用；路径加 `read_image` 已经能让图可见，且不依赖任何服务契约。
+- **驱动被强杀可能遗留 MATLAB 进程。** 驱动在 `atexit` 里退出引擎，但被硬终止时 `atexit` 不会执行。用 `matlab_session` 的 `action="stop"` 正常收尾。
+- **MATLAB 忙时查询会排队。** 引擎在单线程上串行处理请求，所以后台运行未命中时发出的 `dbstack` 探测会阻塞到该调用让出控制权。`run` 已改为先查完成状态再探栈，规避了最糟的情况。
+- **单步调试目前只在 Windows 上验证过。** 引擎铺开逻辑支持 `glnxa64` 与 `maca64`/`maci64`，但只有 Windows 跑过完整的端到端。欢迎其他平台的反馈。
+
+## 许可
+
+[MIT](LICENSE)。本包不再分发任何 MathWorks 代码；见许可文件末尾的说明。

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# matlab-bridge bundle layer: register the tool plugin row.
+#
+# `dsh plugin --profile <profile> add @alotop/dsh-matlab-bridge` installs this
+# package and composes this row into the profile. Declaring it here instead of
+# asking the user to paste the row into a preset is what makes the package
+# self-contained and lets `dsh plugin add` activate it on its own -- without a
+# dsh.bundle in package.json the install is recorded as a plain dependency and
+# nothing is registered.
+#
+# The row publishes no service, only registers tools, so it sits loose and needs
+# no `isolate` realm.
+- insert:
+    - id: matlab-bridge
+      name: '@alotop/dsh-matlab-bridge'

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@alotop/dsh-matlab-bridge",
+  "version": "0.1.1",
+  "description": "Run and interactively debug MATLAB code from a DSH session, through a persistent MATLAB Engine session.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "matlab",
+    "debugger",
+    "matlab-engine"
+  ],
+  "license": "MIT",
+  "author": "alotop",
+  "type": "module",
+  "exports": {
+    ".": "./src/plugin.mjs"
+  },
+  "bin": {
+    "dsh-matlab-bridge-setup": "scripts/setup-engine.mjs"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "cordis.patch.yml",
+    "python/ml_driver.py",
+    "python/mfiles",
+    "python/selftest.py",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "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"
+  },
+  "bugs": {
+    "url": "https://github.com/alotop/dsh-matlab-bridge/issues"
+  },
+  "homepage": "https://github.com/alotop/dsh-matlab-bridge#readme",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/python/mfiles/dsh_evalbase.m

@@ -0,0 +1,31 @@
+function r = dsh_evalbase(code)
+%DSH_EVALBASE Execute CODE in the base workspace, capturing output and errors.
+%
+% Evaluation is forced into the base workspace via EVALIN so variables persist
+% across calls; a function-local EVAL would discard them as soon as the call
+% returned.
+%
+% EVALIN is deliberately asked for NO output argument, and that is what makes
+% the capture match the command window: an assignment echoes `x = 41`, a bare
+% expression echoes `ans = 42`, and a statement with no value prints nothing.
+% Requesting an output argument instead suppresses all three, which is why no
+% caller should try to reconstruct the echo by inspecting the value afterwards.
+%
+% Returns a struct:
+%   out   - captured command-window text
+%   err   - error message, empty on success
+%   stack - formatted error stack, empty when unavailable
+
+  r = struct('out', '', 'err', '', 'stack', '');
+
+  try
+    r.out = evalc('evalin(''base'', code)');
+  catch err
+    r.err = err.message;
+    if ~isempty(err.stack)
+      parts = arrayfun(@(s) sprintf('%s (line %d)', s.name, s.line), ...
+                       err.stack, 'UniformOutput', false);
+      r.stack = strjoin(parts, newline);
+    end
+  end
+end

package/python/mfiles/dsh_figure_info.m

@@ -0,0 +1,29 @@
+function payload = dsh_figure_info()
+%DSH_FIGURE_INFO Describe every open figure, in creation order, as JSON.
+%
+% Returning JSON text rather than a struct array keeps the Python side free of
+% MATLAB struct-array marshalling rules: the driver only ever calls
+% `json.loads` on this.
+%
+% An empty array is a legitimate answer (no figures are open), not an error.
+
+  figs = flipud(findobj('Type', 'figure'));
+
+  info = struct('number', {}, 'name', {}, 'visible', {});
+  for k = 1:numel(figs)
+    f = figs(k);
+    try
+      name = char(f.Name);
+    catch
+      name = '';
+    end
+    try
+      visible = char(f.Visible);
+    catch
+      visible = 'unknown';
+    end
+    info(end + 1) = struct('number', double(f.Number), 'name', name, 'visible', visible);
+  end
+
+  payload = jsonencode(info);
+end

package/python/mfiles/dsh_figure_save.m

@@ -0,0 +1,37 @@
+function payload = dsh_figure_save(dirPath, which)
+%DSH_FIGURE_SAVE Export figures to PNG files and report where each landed, as JSON.
+%
+% WHICH selects the figures: 0 exports every open figure, a positive number
+% exports just that figure. Each becomes figure-<N>.png under DIRPATH.
+%
+% One figure failing to export (an unsupported renderer, a zero-size canvas)
+% must not lose the others, so failures are reported per figure in the `error`
+% field rather than raised; the caller sees which ones worked.
+%
+% JSON text rather than a struct array, so the Python side needs no
+% struct-array marshalling -- see dsh_figure_info for the same reasoning.
+
+  if ~exist(dirPath, 'dir')
+    mkdir(dirPath);
+  end
+
+  if which == 0
+    figs = flipud(findobj('Type', 'figure'));
+  else
+    figs = findobj('Type', 'figure', 'Number', which);
+  end
+
+  results = struct('number', {}, 'path', {}, 'error', {});
+  for k = 1:numel(figs)
+    f = figs(k);
+    file = fullfile(dirPath, sprintf('figure-%d.png', f.Number));
+    try
+      exportgraphics(f, file, 'Resolution', 150);
+      results(end + 1) = struct('number', double(f.Number), 'path', file, 'error', '');
+    catch err
+      results(end + 1) = struct('number', double(f.Number), 'path', '', 'error', err.message);
+    end
+  end
+
+  payload = jsonencode(results);
+end