dsh-plugin-update-checker 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 windrover
+
+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.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# dsh-plugin-update-checker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> [English](./README.md) · [中文](./README.zh-CN.md)
+
+A DeepSeek Harness plugin that adds a **Check updates** button to the **Built-in plugins** settings section. Click it and the plugin scans every installed plugin bundle for (1) the latest published version on the npm registry and (2) its compatibility with the running DSH runtime — then shows one row per bundle.
+
+It lives beside the read-only inventory tab and contributes **no configuration** of its own. It reports, and for any bundle with a published update it offers a single **Update** button (the same `installBundle` primitive the GUI's *Add plugin* dialog uses). Enabling, disabling, or removing a bundle is still done in the sidebar **Plugins** page or via `dsh plugin`.
+
+## ✨ What it does
+
+| Check | Source | Notes |
+|---|---|---|
+| **Update availability** | npm registry (`latest` dist-tag vs the installed version) | Registry-only. Bundles installed from a tarball / git / path publish nothing, so they are reported as *Unsupported* rather than falsely *Up to date*. |
+| **Compatibility** | the bundle's `@deepseek-ai/dsh*` `peerDependencies` vs the running DSH version | Reuses `@deepseek-ai/dsh-app-boot`'s `evaluatePluginCompatibility`, the same helper the launcher applies on boot. An exact-version exemption granted in `compatibility.json` shows as *Compatible (exempted)*. |
+
+Compatibility and update availability are computed **independently** — a slow or unreachable registry can never hide an incompatible peer range, and a local-only bundle still gets a compatibility verdict.
+
+**Which registry the scan asks**: no longer a hardcoded `registry.npmjs.org`. The host reads the configuration itself (environment → the profile's `.npmrc` → the user's `~/.npmrc`, first hit wins) and then **probes the candidates concurrently, taking the first success**. Three cases: **nothing configured** → race the launcher's mirror against the public registry; **the public default configured** (npm writes `registry=https://registry.npmjs.org/` into `~/.npmrc` on its own) → keep it and add the mirror behind it, since both are public and nothing leaks; **anything else configured** (a corporate or internal registry) → **that one alone, never raced against a public registry**, because racing would leak internal package names to third parties. The difference is large behind a slow link — measured on one machine, the public registry answered in ~11 s where a mirror answered in ~0.2 s, and racing means a slow registry cannot hold up a fast one even when it is listed first. A bundle that declares `publishConfig.registry` still uses that registry. The winning registry travels with the row and is reused by the one-click update, so **the version is read from, and installed from, the same place**.
+
+> The host half declares only `webServer`, and `remote` is a **browser-side** service; in this cordis version, touching an undeclared service throws (`cannot get property ... without inject`). The host therefore cannot ask the plugin manager for registries — reading the configuration, as above, is what that constraint requires.
+
+## 📸 Where it sits
+
+Open **Settings → Built-in plugins**. The section now has two tabs:
+
+- **Plugin list** — the read-only inventory (shipped by DSH).
+- **Check updates** — this plugin. It shows the running DSH version, a **Check updates** button, and the results table (plugin / installed / latest / compatibility / update).
+
+The check is on demand: click the button, the host scans, and the table fills in. One broken manifest or an unreachable registry is isolated to its own row — it never blanks the whole report.
+
+## 📦 Install
+
+### Option A — from npm (recommended)
+
+```bash
+dsh install-plugin dsh-plugin-update-checker
+```
+
+Installing from the registry matters for this plugin in particular: a `github:`
+install is pinned to a commit in the profile lockfile, so re-running the same
+spec never picks up a newer release, and the panel reports it as *Unsupported*
+(it can only compare registry versions). From `0.1.4` on, plain version numbers
+resolve normally and the panel's own **Update** button works.
+
+### Option B — from this GitHub repository
+
+1. Open the sidebar **Plugins** page → **Add plugin**.
+2. In the source field, enter one of these install specs (the launcher resolves them through `installBundle`, the same primitive the GUI uses):
+
+   ```text
+   github:windrover/dsh-plugin-update-checker
+   # or the full URL:
+   https://github.com/windrover/dsh-plugin-update-checker
+   ```
+
+3. Restart to load the new bundle:
+
+   ```bash
+   dsh check     # iron rule #1: preflight before restart
+   dsh restart   # reloads the web profile; the new bundle loads
+   ```
+
+4. Open **Settings → Built-in plugins → Check updates → Check updates.**
+   The Check button's `fetch('/api/plugin-update-checker/scan')` runs inside the
+   authenticated browser session, so it needs no manual token.
+
+> This repository is **public**, so installing directly from GitHub works without any
+> extra authentication. On networks where `registry.npmjs.org` is unreachable, the
+> launcher uses `registry.npmmirror.com` automatically.
+
+### Option B — local link (for development / editing the plugin)
+
+1. Clone the package where your profile can link it:
+
+   ```bash
+   # e.g. inside your DSH workspace
+   git clone https://github.com/windrover/dsh-plugin-update-checker dsh-plugin-update-checker
+   ```
+
+2. Link it into your profile. Add a `link:` dependency + a `bundles` entry to the profile manifest:
+
+   ```jsonc
+   // ~/.dsh/profiles/web/package.json
+   {
+     "dependencies": {
+       "dsh-plugin-update-checker": "link:/abs/path/to/dsh-plugin-update-checker"
+     },
+     "dsh": { "profile": { "bundles": [ "…", "dsh-plugin-update-checker" ] } }
+   }
+   ```
+
+   Then install. **`npm install` rejects the `link:` protocol** in this profile — use `pnpm` (the profile is a pnpm workspace), which is what `dsh` wires under the hood:
+
+   ```bash
+   cd ~/.dsh/profiles/web
+   pnpm install --registry=https://registry.npmmirror.com   # link: deps don't hit the network
+   ```
+
+   `dsh`'s `wire_link_plugin_deps` auto-symlinks any `@deepseek-ai/*` the plugin
+   imports into its own `node_modules`, but **it does not handle plain npm packages** —
+   so pre-link the one real dependency yourself (the documented link-plugin gotcha:
+   a `link:` plugin can't resolve packages that aren't hoisted into its tree):
+
+   ```bash
+   mkdir -p dsh-plugin-update-checker/node_modules
+   ln -sfn ~/.npm/_npx/<active-dsh-hash>/node_modules/semver \
+           dsh-plugin-update-checker/node_modules/semver
+   ```
+
+3. Restart and open it (`dsh check && dsh restart`, then the same Settings path as Option A).
+
+## 🔌 How it is built
+
+One bundle, two halves:
+
+- **Host** (`lib/index.js` → `lib/host/update-checker.js`) registers `POST /api/plugin-update-checker/scan`, which walks the profile's bundles (via `ctx.remote.pluginManager.listBundles()`, falling back to scanning `node_modules`), reads each manifest, evaluates peer compatibility, and probes the registry. `cordis.patch.yml` adds the Loader row.
+- **Browser** (`lib/client.js`) registers a tab into the `settings.plugins.tab` slot of the Built-in-plugins section and renders the result with `react` (`require("react")`) and the design tokens DSH already exposes. The bundle `id` equals the package `name` — the contract `dsh-client-modules` enforces.
+
+## 🧪 Test
+
+```bash
+node test/client-contract.test.mjs
+```
+
+Pins the browser-half contract (id == package name, one `settings.plugins.tab` registration, renderable body). The host scan was exercised against the live profile during development and returns `{ ok, dshVersion, checkedAt, plugins: [...] }`.
+
+## 📝 Limitations
+
+- **Reports and updates, does not toggle** — it never enables, disables, or removes a bundle, and it cannot change its configuration. A failed update is reported per row, not retried automatically.
+- **Registry reachability** — registry checks need network access to the configured registry; offline or firewalled hosts show *Unknown* per bundle.
+- **Local / git / tarball bundles** — publish no registry version, so their update status is *Unsupported*. Their compatibility is still evaluated from the local manifest.

package/README.zh-CN.md

@@ -0,0 +1,123 @@
+# dsh-plugin-update-checker
+
+> [中文](./README.zh-CN.md) · [English](./README.md)
+
+一个 DeepSeek Harness 插件：在 **内置插件（Built-in plugins）** 设置分区中增加一个 **检查更新（Check updates）** 按钮。点击后，它会扫描每个已安装插件的 (1) npm 上的最新发布版本 与 (2) 与当前运行 DSH 运行时的兼容性，并以每个插件一行的形式展示结果。
+
+它与只读的插件清单页并列，本身**不提供任何配置**。它负责汇报，并对有可用更新的插件提供一个 **更新** 按钮（与 GUI「添加插件」走同一个 `installBundle`）。启用、停用、卸载插件仍然在右侧栏的 **插件（Plugins）** 页面或通过 `dsh plugin` 完成。
+
+## ✨ 它做什么
+
+| 检查项 | 数据来源 | 说明 |
+|---|---|---|
+| **更新可用性** | npm 注册表（`latest` tag 与已安装版本对比） | 仅针对发布到注册表的包。通过 tarball / git / 本地路径安装的包不会发布到注册表，因此显示为 *不受支持（Unsupported）*，而绝不会错误地显示 *已是最新*。 |
+| **兼容性** | 插件的 `@deepseek-ai/dsh*` `peerDependencies` 与当前 DSH 版本对比 | 复用 `@deepseek-ai/dsh-app-boot` 的 `evaluatePluginCompatibility`——也就是启动器在启动时用的同一个判断函数。若在 `compatibility.json` 中授予了精确版本豁免，则显示为 *兼容（已豁免）*。 |
+
+兼容性与更新可用性是**独立计算**的——注册表慢或不可达，永远不会掩盖不兼容的 peer 依赖；反之，纯本地包仍然会得到兼容性结论。
+
+**扫描用哪个注册表**：不再写死 `registry.npmjs.org`。主机自己读配置（环境变量 → profile 的 `.npmrc` → 用户 `~/.npmrc`，取第一个命中的），再**并发探测、取最先成功的那个**。规则分三种：**什么都没配** → 竞速「启动器同款镜像 + 公共注册表」；**配的是公共默认值**（npm 会自动往 `~/.npmrc` 写 `registry=https://registry.npmjs.org/`）→ 保留它并把镜像挂在后面，两者皆公共、无泄露风险；**配的是其它地址**（公司内部源、私有源）→ **只用它一个，绝不与任何公共注册表竞速**，否则会把内部包名泄露给第三方。国内网络下差别很大——实测同一台机器上公共注册表约 11s、镜像约 0.2s；竞速保证慢的那个即使排在第一也不会拖住快的。清单里显式声明了 `publishConfig.registry` 的包仍以该注册表为准。获胜注册表随行返回，点「更新」时沿用它——**从哪读到版本，就从哪安装**。
+
+> 宿主半身只声明了 `webServer`，而 `remote` 是**浏览器侧**服务；当前 cordis 版本里访问未声明的服务会直接抛错（`cannot get property ... without inject`），所以宿主**不能**去问插件管理器要注册表——上面这套读配置的方式正是为此设计的。
+
+## 📸 位置
+
+打开 **设置 → 内置插件**。该分区现在有两个标签页：
+
+- **插件清单（Plugin list）** —— 只读清单（由 DSH 自带）。
+- **检查更新（Check updates）** —— 本插件。展示当前 DSH 版本、**检查更新** 按钮，以及结果表格（插件 / 已安装版本 / 最新版本 / 兼容性 / 更新）。
+
+检查是按需触发的：点击按钮，主机扫描，表格填充。某个清单损坏或注册表不可达，只会隔离到对应那一行——绝不会让整张报表空白。
+
+## 📦 安装
+
+### 方式 A —— 从 npm 安装（推荐）
+
+```bash
+dsh install-plugin dsh-plugin-update-checker
+```
+
+从注册表安装对这个插件**尤其值得**：用 `github:` 安装会被 profile 锁文件钉在某个
+commit 上，重跑同样的 spec 不会拿到新版本，面板也只能把它报成 *不受支持*
+（它只会比对注册表版本）。`0.1.4` 之后按普通版本号解析，面板自带的「更新」按钮就能用。
+
+### 方式 B —— 从本 GitHub 仓库直接安装
+
+1. 打开右侧栏 **插件（Plugins）** 页面 → **添加插件**。
+2. 在来源框里填入下面任意一种安装描述符（启动器通过 `installBundle` 解析，和 GUI 用的是同一个原语）：
+
+   ```text
+   github:windrover/dsh-plugin-update-checker
+   # 或完整 URL：
+   https://github.com/windrover/dsh-plugin-update-checker
+   ```
+
+3. 重启以加载新 bundle：
+
+   ```bash
+   dsh check     # 铁律 #1：重启前先预检
+   dsh restart   # 重新加载 web profile，新 bundle 随之加载
+   ```
+
+4. 打开 **设置 → 内置插件 → 检查更新 → 检查更新。**
+   检查按钮发起的 `fetch('/api/plugin-update-checker/scan')` 在已认证的浏览器会话内执行，无需手动 token。
+
+> 本仓库是 **公开** 的，所以从 GitHub 直接安装无需额外认证。在 `registry.npmjs.org` 不可达的网络下，启动器会自动改用 `registry.npmmirror.com`。
+
+### 方式 B —— 本地链接（用于开发 / 改这个插件）
+
+1. 把包 clone 到 profile 能链接的位置：
+
+   ```bash
+   # 例如放在你的 DSH 工作区里
+   git clone https://github.com/windrover/dsh-plugin-update-checker dsh-plugin-update-checker
+   ```
+
+2. 链接进 profile：在 profile 清单中加入 `link:` 依赖与 bundles 条目：
+
+   ```jsonc
+   // ~/.dsh/profiles/<你的 profile>/package.json
+   {
+     "dependencies": {
+       "dsh-plugin-update-checker": "link:/abs/path/to/dsh-plugin-update-checker"
+     },
+     "dsh": { "profile": { "bundles": [ "…", "dsh-plugin-update-checker" ] } }
+   }
+   ```
+
+   然后安装。本 profile 下 **`npm install` 会拒绝 `link:` 协议**——改用 `pnpm`（profile 是 pnpm workspace，这也是 `dsh` 底层用的）：
+
+   ```bash
+   cd ~/.dsh/profiles/web
+   pnpm install --registry=https://registry.npmmirror.com   # link: 依赖不联网
+   ```
+
+   `dsh` 的 `wire_link_plugin_deps` 会自动把插件 import 的 `@deepseek-ai/*` 软链进它自己的 `node_modules`，但**不会处理普通 npm 包**——所以要把那唯一一条真依赖手动预链（link 插件的已知坑：link 插件解析不到没提升到它树里的包）：
+
+   ```bash
+   mkdir -p dsh-plugin-update-checker/node_modules
+   ln -sfn ~/.npm/_npx/<active-dsh-hash>/node_modules/semver \
+           dsh-plugin-update-checker/node_modules/semver
+   ```
+
+3. 重启并打开（`dsh check && dsh restart`，再走方式 A 同样的设置路径）。
+
+## 🔌 实现方式
+
+一个包，两端：
+
+- **主机（Host）**（`lib/index.js` → `lib/host/update-checker.js`）注册 `POST /api/plugin-update-checker/scan`，遍历 profile 的 bundles（通过 `ctx.remote.pluginManager.listBundles()`，回退到扫描 `node_modules`），读取每个清单、评估 peer 兼容性、探测注册表。`cordis.patch.yml` 添加 Loader 行。
+- **浏览器（Browser）**（`lib/client.js`）向内置插件分区的 `settings.plugins.tab` 槽注册一个标签页，并用 `react`（`require("react")`）和 DSH 已暴露的设计 token 渲染结果。包的 `id` 等于包 `name`——这是 `dsh-client-modules` 强制的契约。
+
+## 🧪 测试
+
+```bash
+node test/client-contract.test.mjs
+```
+
+锁定浏览器半边的契约（id == 包名、唯一一个 `settings.plugins.tab` 注册、可渲染的 body 组件）。主机扫描已在开发期对真实 profile 演练过，返回 `{ ok, dshVersion, checkedAt, plugins: [...] }`。
+
+## 📝 局限
+
+- **只汇报与更新，不启停** —— 不会启用/停用/卸载插件，也不能改配置；更新失败按行回报，不自动重试。
+- **注册表可达性** —— 注册表检查需要能访问所配置注册表的网络；离线或防火墙后的主机每个包显示 *未知（Unknown）*。
+- **本地 / git / tarball 包** —— 不发布注册表版本，其更新状态为 *不受支持*；兼容性仍由本地清单评估。

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-plugin-update-checker bundle patch.
+#
+# `name` MUST equal package.json's `name` exactly, case included: the
+# dsh-client-modules Loader row resolver walks up from the resolved module path
+# to the package.json whose `name` strictly equals this specifier, then requires
+# the browser bundle to register that same id via __ModuleLoader__.load. A case
+# mismatch silently drops the whole browser half out of the boot graph while the
+# host half (the web route) keeps working.
+#
+# Applied after dsh-web-app; the user's own cordis.patch.yml can still override
+# the row by id.
+- insert:
+    - id: plugin-update-checker
+      name: dsh-plugin-update-checker