dsh-plugin-upgrader 1.6.1 → 1.6.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.6.2 — 2026-11-02
+
+- **A DSH Store notice was re-checked against the current code, not taken at face value.**
+  Issue #1550 listed eight reasons, but they were a scan of v1.0.1: four of them (the three
+  missing runtime artifacts and the incomplete scan) and `prepare`/`engines.dsh` were all
+  fixed in 1.5.0. Re-running the store's own review code against the current tree leaves
+  one catalog reason this release could act on — the runtime dependency — and three
+  capability signals (`files`, `network`, `credentials`) that are the plugin's actual job.
+  Those three sit on the store's review list rather than its reject list, so they need a
+  maintainer admission record, not a code change; rewriting the plugin to stop touching
+  files, the network or the environment would be removing the feature.
+- **`@deepseek-ai/schemastery` is a peer dependency, not a bundled one.** 1.6.0 declared it
+  as a dependency so the `Config` schema would be built by the same library the loader
+  validates with — but that argument points at a peer, not at a copy: a peer guarantees one
+  instance, while a bundled copy can produce two. The host already ships it (`DSH desktop`
+  depends on it directly and `dsh-plugin-manager` does too), so the package no longer pulls
+  its own. It stays in `devDependencies` for building and testing.
+- **The package now declares per-release DSH compatibility.** `dsh.compatibility.dshReleases`
+  records `0.2.1-rc.5` as `compatible` — the release this plugin actually runs on. The two
+  other releases in the rolling window (`0.2.1-rc.4`, `0.2.2-alpha.2`) are inside the
+  `engines.dsh` range but were never exercised here, so they are deliberately left
+  undeclared and read as `unknown`. `dshOperations` is left out for the same reason rather
+  than filled with `passed`. This is Catalog metadata only; the host does not read it.
+- **README gains a permissions / dependencies / external services / failure-bounds section**
+  in both languages, so a review does not have to infer the blast radius from the source.
+
 ## 1.6.1 — 2026-10-30
 
 - **The source test no longer calls a working mirror unreachable.** The probe tried

package/README.en.md

@@ -12,7 +12,7 @@ plugin adds a **Versions** tab to that page and fills both gaps.
 
 English · [中文](./README.md)
 
-![Versions tab](./screenshots/history.png)
+![Versions tab](https://raw.githubusercontent.com/zuwenyin/dsh-plugin-upgrader/main/screenshots/history.png)
 
 ## Features
 
@@ -39,6 +39,8 @@ English · [中文](./README.md)
   Built-ins cannot be edited or deleted; your own can. Every row can be tested on its
   own, and so can the source currently in use.
 
+![Source manager](https://raw.githubusercontent.com/zuwenyin/dsh-plugin-upgrader/main/screenshots/sources.png)
+
 > **Changing this repo? Read [AGENTS.md](./AGENTS.md) first.** It lists the behaviour
 > that already works and must keep working, with the code location and the test that
 > guards each one. Two of those features (the `GH` links and the in-place upgrade)
@@ -46,7 +48,9 @@ English · [中文](./README.md)
 
 ## Where it shows up
 
-A **Versions** tab appears next to *Installed* and *Discover* on the Plugins page:
+A **Versions** tab appears next to *Installed* and the market tab on the Plugins
+page (that tab is **Market** with `dshmarket` installed, and **Discover** in DSH's
+own market page):
 
 - Header counts: upgradable / installed / version count
 - The header **Registry** control opens the source dialog:
@@ -72,11 +76,12 @@ A **Versions** tab appears next to *Installed* and *Discover* on the Plugins pag
   - the version was not tagged, or the GitHub list is unreadable (rate limit,
     offline) → the repository's `releases` feed
 
-![Expanded history](./screenshots/selection.png)
+![Expanded history](https://raw.githubusercontent.com/zuwenyin/dsh-plugin-upgrader/main/screenshots/selection.png)
 
 ## Install
 
-Search `dsh-plugin-upgrader` on the Plugins page's **Discover** tab and hit install.
+Search `dsh-plugin-upgrader` on the Plugins page's market tab (**Discover** in DSH
+itself, **Market** with `dshmarket` installed) and hit install.
 On the desktop app use its own plugin manager — the CLI cannot change the profile
 an app has open.
 
@@ -215,6 +220,88 @@ error:
 A restart interrupts the job in flight; the UI reports that as a failure rather than
 spinning forever.
 
+## Permissions, dependencies and external services
+
+This section states the capabilities the plugin actually uses, so a review or a bug
+report does not have to read the source to find out.
+
+### What it touches
+
+| Capability | Scope | Notes |
+| --- | --- | --- |
+| Files | **the profile directory only** | Reads and writes `package.json`, writes `package.json.upgrader-journal.json`, reads `package.json.lock`. No filesystem walking, nothing outside the profile |
+| Network (outbound) | the configured npm registry, the GitHub API | `GET` only, see below |
+| Commands | **none** | No `child_process`, no spawned processes; installs go through the host's `pluginManager` |
+| Credentials | **none** | No tokens, no `.npmrc` reads, no authentication. Private registries rely on pnpm's own configuration |
+
+The registry choice (`registry` / `customRegistries`) is written into the profile's
+`cordis.patch.yml` by the **host's settings service**, not by the plugin editing files:
+the plugin only calls `configForms.set()`.
+
+Three environment variables are read, all to *locate the profile directory*:
+`DSH_PROFILE_DIR`, `DSH_HOME` and `DSH_PROFILE`. When the desktop shell exports none of
+them, a working directory that parses as a profile is used instead. They are not
+secrets, but a bare `process.env` counts as one "credentials" signal in a static scan,
+so the real purpose is spelled out here.
+
+### External services
+
+| Target | Purpose | On failure |
+| --- | --- | --- |
+| `{configured npm registry}/{package}` | packument fetch, to list published versions (5 minute cache, 20 second timeout, at most 4 concurrent) | that row shows `versionError` and a retry entry; other rows are unaffected |
+| `https://registry.npmjs.org/{package}` | only when the configured registry is not the official one: an extra upstream check that reports a lagging mirror | an unreadable upstream means "no gap", never "everything is missing" |
+| `https://api.github.com/repos/{owner}/{repo}/tags?per_page=100` | tag list, to decide whether a version can link to `releases/tag/v…` (30 minute cache, 8 second timeout) | falls back to the `releases` list; never guesses a tag that 404s |
+| `{the address being tested}/-/ping` and its root | *Test* in the Registry dialog probes both **concurrently**, first 2xx wins (5 s budget for the whole probe) | reports the most specific reason: status code first, then timeout, then the raw network error |
+| the local DSH web server | the plugin's own four `/api/plugin-upgrader/*` routes | — |
+
+The default registry is whatever pnpm is configured with (usually `.npmrc`); the
+**Registry** button on the Versions tab switches to the official registry, mainland
+mirror, or a source you add yourself. **No telemetry** of any kind is sent.
+
+### Dependencies
+
+There are **no bundled runtime dependencies**. The single external module,
+`@deepseek-ai/schemastery` (used for the Config schema, `~3.18.5`), is declared in
+`peerDependencies` and supplied by the host: DSH desktop ships it as its own dependency
+and first-party packages such as `dsh-plugin-manager` depend on it too, so it always
+resolves inside a profile. The copy needed for building and testing lives in
+`devDependencies`.
+
+The remaining `devDependencies` (TypeScript, esbuild, `@types/*`, `@deepseek-ai/dsh-*`)
+are development-time only and are not part of the published tarball's runtime.
+
+### Failure bounds
+
+- **One batch at a time**: a second submission gets `409 busy`; the UI adopts the batch
+  that is running instead of reporting an error.
+- **A job heartbeats every 2 seconds** and is declared abandoned after 15 minutes of
+  no progress, so it cannot occupy the slot forever. A host restart interrupts the job
+  in flight and the UI reports that as a failure.
+- **Writer lock**: the manager's own budget is 120 seconds; a timeout is translated
+  into who holds the lock and whether a restart clears it.
+- **A failed upgrade**: the in-place path journals the dropped dependency before
+  removing it and restores it on failure; a killed process is repaired on the next
+  load. The plugin stays installed and keeps its enabled state.
+- **Unreachable registry, rate-limited GitHub, offline**: every one of them degrades to
+  "this one thing could not be read, here is why, retry", never to a silent "no new
+  version" or "no version history".
+
+### DSH compatibility
+
+Node.js `>=20` and DSH `>=0.2.1-rc.3 <0.3.0-0` (the `engines` field).
+`dsh.compatibility.dshReleases` records **only the releases actually exercised**:
+
+| DSH release | Status |
+| --- | --- |
+| `0.2.1-rc.5` | compatible |
+
+`0.2.1-rc.4` and `0.2.2-alpha.2` fall inside the `engines` range but were not each
+exercised, so they are **not** listed (an undeclared release reads as `unknown`). These
+are **source-side compatibility declarations**, not a substitute for per-operation
+acceptance. `dshOperations` (install / start / uninstall / rollback) follows the same
+rule: left out rather than filled with `passed` before there is a per-release run behind
+it.
+
 ## Project layout
 
 ```

package/README.md

@@ -10,7 +10,7 @@ DSH 自带的插件页能装、能卸、能看已安装列表，但缺两件事
 
 [English](./README.en.md) · 中文
 
-![版本标签](./screenshots/history.png)
+![版本标签](https://raw.githubusercontent.com/zuwenyin/dsh-plugin-upgrader/main/screenshots/history.png)
 
 ## 功能
 
@@ -29,13 +29,16 @@ DSH 自带的插件页能装、能卸、能看已安装列表，但缺两件事
   和用户自己加的源；自带源不能改也不能删，自己加的可以随时改/删。每一行都能单独
   「测试」能不能连上，当前在用的那个也能一键测。
 
+![安装源管理](https://raw.githubusercontent.com/zuwenyin/dsh-plugin-upgrader/main/screenshots/sources.png)
+
 > **要改这个仓库？先读 [AGENTS.md](./AGENTS.md)。** 那里逐条写了「已经实现并且必须继续成立」
 > 的行为、对应代码位置和守护它的测试。上面这些功能里，`GH` 链接和 in-place 升级都曾经
 > 被无意改掉过一次。
 
 ## 界面位置
 
-插件页顶部标签栏多出一个「版本」标签，与「已安装」「发现」并列：
+插件页顶部标签栏多出一个「版本」标签，与「已安装」以及市场标签并列
+（市场标签在装了 `dshmarket` 的界面里叫「插件市场」，DSH 自带的那个叫「发现」）：
 
 - 顶部统计：可升级数量 / 已安装数量 / 每个插件的版本数
 - 顶部「注册表」按钮打开安装源对话框：
@@ -57,11 +60,12 @@ DSH 自带的插件页能装、能卸、能看已安装列表，但缺两件事
   - 该版本没打 tag，或 GitHub 列表读不到（限流 / 离线）→ 退回仓库的发布列表 `releases`，
     不在页面上放一个点进去是 404 的版本号
 
-![展开历史版本](./screenshots/selection.png)
+![展开历史版本](https://raw.githubusercontent.com/zuwenyin/dsh-plugin-upgrader/main/screenshots/selection.png)
 
 ## 安装
 
-在「插件」页的**发现**标签里搜索 `dsh-plugin-upgrader`，点安装即可。
+在「插件」页的市场标签里搜索 `dsh-plugin-upgrader`（自带的是「发现」，
+装了 `dshmarket` 的界面里叫「插件市场」），点安装即可。
 桌面版请用它自带的插件管理界面安装，命令行改动不了正在运行的桌面 profile。
 
 用 `dsh` 命令行（把 `web` 换成你自己的 profile 名）：
@@ -181,6 +185,74 @@ atomic-write: timed out waiting for the writer lock at …/package.json.lock
 
 主进程重启会让正在跑的 job 中断，界面会把这种情况显示为失败而不是永远转圈。
 
+## 权限、依赖与外部服务
+
+这一节把插件实际用到的能力写清楚，方便审核和排障时对照，而不是让人去读源码猜。
+
+### 读写什么
+
+| 能力 | 范围 | 说明 |
+| --- | --- | --- |
+| 文件 | **仅 profile 目录** | 读写 `package.json`、写 `package.json.upgrader-journal.json`、读 `package.json.lock`。不遍历文件系统，不碰 profile 以外的路径 |
+| 网络（出站） | 配置的 npm 源、GitHub API | 只发 `GET`，见下 |
+| 命令 | **无** | 不调用 `child_process`，不 spawn 任何进程；安装动作交给宿主的 `pluginManager` |
+| 凭据 | **无** | 不读 token，不读 `.npmrc`，不做任何认证。私有源依赖 pnpm 自己的配置 |
+
+安装源的选择（`registry` / `customRegistries`）由**宿主的设置服务**写进 profile 的
+`cordis.patch.yml`，不是插件自己改文件——插件只调 `configForms` 的 `set()`。
+
+宿主进程的环境变量只用了 `DSH_PROFILE_DIR` / `DSH_HOME` / `DSH_PROFILE` 三个来**定位 profile
+目录**（桌面壳不导出它们时，退回「当前工作目录看起来像不像一个 profile」）。它们不是密钥，但
+静态扫描器会把裸 `process.env` 记成一次「凭据」信号，这里说明清楚它的真实用途。
+
+### 外部服务
+
+| 目标 | 用途 | 失败时 |
+| --- | --- | --- |
+| `{配置的 npm 源}/{包名}` | 拉 packument，列出已发布版本（5 分钟缓存，20 秒超时，最多 4 个并发） | 该行显示 `versionError` 和「重试」，其它行不受影响 |
+| `https://registry.npmjs.org/{包名}` | 只当配置的不是官方源时，额外查一次上游，报告「镜像落后」 | 读不到就当作没有缺口 |
+| `https://api.github.com/repos/{owner}/{repo}/tags?per_page=100` | 取 tag 列表，判断某个版本号能不能链到 `releases/tag/v…`（30 分钟缓存，8 秒超时） | 退到 `releases` 列表页，绝不猜一个 404 的 tag |
+| `{被测试的地址}/-/ping` 与根地址 | 「注册表」对话框里点「测试」时，**并发**探测这两条，谁先 2xx 用谁（整次探测 5 秒预算） | 报最具体的原因：状态码优先，其次超时，最后网络错误原文 |
+| 本机 DSH Web 服务 | `/api/plugin-upgrader/*` 自己的四个路由 | — |
+
+默认源是 pnpm 自己配置的那个（通常是 `.npmrc` 里的），也可以在「版本」页的「注册表」按钮里
+换成官方源、大陆镜像或自己加的源。**没有任何遥测**，不向第三方发送使用数据。
+
+### 依赖
+
+运行时**没有自带依赖**。唯一的外部模块 `@deepseek-ai/schemastery`（Config schema 用，要求
+`~3.18.5`）声明在 `peerDependencies` 里，由宿主提供——DSH 桌面端把它作为自身依赖发布，
+`dsh-plugin-manager` 等第一方包也依赖它，所以 profile 里一定解析得到。构建和测试需要的那一份
+放在 `devDependencies`。
+
+`devDependencies` 其余各项（TypeScript、esbuild、`@types/*`、`@deepseek-ai/dsh-*`）只在开发和
+构建时使用，不会进入发布的 tarball 运行时。
+
+### 失败边界
+
+- **一次只跑一批**：第二个提交拿 `409 busy`，界面接管正在跑的那一批，不报错。
+- **job 心跳 2 秒**，15 分钟没进展判废，不会永久占位；主进程重启会中断正在跑的 job，
+  界面显示为失败而不是永远转圈。
+- **写入锁**：manager 自己的预算是 120 秒，超时会把锁的状态翻成人话（谁持有、要不要重启）。
+- **升级失败**：in-place 替换会先把被摘掉的依赖记进 journal，失败就还原；进程被杀掉时，
+  下次加载会把依赖补回去。失败了插件仍在、启用状态仍在。
+- **registry 读不到 / GitHub 限流 / 离线**：都降级成「这一项读不到 + 原因 + 重试入口」，
+  不会伪装成「没有新版本」「没有历史版本」。
+
+### DSH 兼容性
+
+要求 Node.js `>=20`，DSH `>=0.2.1-rc.3 <0.3.0-0`（`package.json` 的 `engines`）。
+`dsh.compatibility.dshReleases` 只记录**真的跑过**的版本：
+
+| DSH 版本 | 状态 |
+| --- | --- |
+| `0.2.1-rc.5` | compatible |
+
+`0.2.1-rc.4` 和 `0.2.2-alpha.2` 虽然落在 `engines` 范围内，但没有逐一实测过，所以**不写进去**
+（未声明的版本按 `unknown` 处理）。这是**来源侧的兼容声明**，不代替逐项的操作验收；
+`dshOperations`（install / start / uninstall / rollback）同理，没有逐版本的实测记录就留空，
+不写 `passed`。
+
 ## 项目结构
 
 ```

package/lib/host/overview.js

@@ -1,8 +1,8 @@
 /**
  * The overview payload the Versions tab renders.
  *
- * One request answers everything the tab needs 鈥?installed bundles, their
- * published versions, which of them are upgradable 鈥?because a per-bundle
+ * One request answers everything the tab needs — installed bundles, their
+ * published versions, which of them are upgradable — because a per-bundle
  * request would turn one page open into a dozen round trips.
  *
  * @module dsh-plugin-upgrader/lib/overview
@@ -19,7 +19,7 @@ const INLINE_ICON_LIMIT = 2048;
  * The first version of this used `Promise.all`, which fired every package
  * lookup at the mirror simultaneously. Eleven concurrent connections to
  * `registry.npmmirror.com` timed out, while the same eleven asked one at a time
- * answered in under 1.2 s 鈥?and each timeout rendered as a plugin with no
+ * answered in under 1.2 s — and each timeout rendered as a plugin with no
  * version history. The cap is what keeps one page load from becoming a burst.
  *
  * @param items - the work items.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-upgrader",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "One-click upgrades, version history and rollback for plugins on the DeepSeek Harness Plugins page",
   "keywords": [
     "dsh",
@@ -62,6 +62,11 @@
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-settings"
       ]
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.1-rc.5": "compatible"
+      }
     }
   },
   "devDependencies": {
@@ -70,12 +75,13 @@
     "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-host-webserver": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-plugin-manager": "^0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "~3.18.5",
     "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2"
   },
-  "dependencies": {
+  "peerDependencies": {
     "@deepseek-ai/schemastery": "~3.18.5"
   },
   "scripts": {