dsh-plugin-toolkit 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.13.3
+
+- **`verify` no longer fails a correct plugin.** The check that calls a client
+  module's `apply()` before its services exist handed it `{}`, so
+  `ctx.inject(...)` — the cordis API every plugin uses — threw
+  `ctx.inject is not a function` and the plugin was reported as broken. The
+  probe now models a real context: `inject`, `on`, `effect`, `logger`, `get`,
+  `set` and `provide` exist; only the services are absent.
+- Found by this repository's own example plugin, whose CI went red on the
+  previous release. That is the whole point of the example.
+
+## 0.13.2
+
+- **A table of the four ways a plugin installs and still does nothing** — red
+  dot with no panel, a row the host drops, an app that disables every plugin
+  after one unguarded `apply()`, and a tab type nothing can open. Each row is a
+  bug this toolkit shipped and then learned to catch, and each row names the
+  check that catches it now.
+- Both READMEs. Nothing in the code changed.
+
 ## 0.13.1
 
 - **A badge you can put on a plugin that passes.** `docs/badge.svg` plus the

package/README.md

@@ -73,6 +73,19 @@ Releasing one plugin fifteen times taught me three things the ecosystem's toolin
 2. **The market index is a second release, done by hand.** Each version needs an entry carrying `publishTimestamp` from the registry and `engines.dsh` from the manifest. Forget the range and the index validator rejects the PR with `Engines mismatch` — after the tag is already public.
 3. **Reading a manifest is not the same as checking it.** A plugin can have a valid `package.json` and still be uninstallable: `files` that omit the entry the manifest points at, a bundle patch that does not exist, a README that never states the host range it declares.
 
+### Four ways a plugin installs and still does nothing
+
+Each of these shipped in a real version of this toolkit before the check below existed. A manifest check passes on all four.
+
+| What you see | What it was | Caught by |
+| --- | --- | --- |
+| The tab is a red dot and the panel never opens | `exports["."]` pointed at the CLI, so the loader's row had no plugin to apply | `root export` |
+| The plugin is installed, the app never serves it | `dsh.client` declared, `exports["./client"]` missing — the host drops the row | `client declaration` |
+| The app says the third-party plugin is unsupported and disables all of them | `apply()` read `ctx.webServer` without declaring it; cordis throws instead of returning `undefined` | `verify` (calls `apply` on a context that has no services) |
+| The tab registers, and nothing in the UI opens it | `sidebarRightTabs.register()` registers a *type*; the sidebar lists what `tabs.guide()` returns | a testkit test, not `doctor` |
+
+The first three are static: `doctor` and `verify` catch them without the app running. The fourth is a UI contract, so it needs the panel mounted and the registration inspected — that is what [`testkit`](#test-a-panel-without-a-browser) is for.
+
 ## Requirements
 
 - Node.js 18 or newer (the registry is read with `fetch`; no runtime dependencies)

package/README.zh.md

@@ -31,6 +31,19 @@ npx dsh-plugin-toolkit@latest release --pr --merge              # 打 tag、等
 
 每一条都能在发布前被机器拦住，所以每一条现在都是一项检查。这些检查对着**宿主的解析代码**写，而不是对着文件约定写——差别就是 `verify` 报 `mounted the panel` 而真实宿主什么都不加载。
 
+### 插件装上了却什么都不做的四种样子
+
+下面每一条都真实发布过，而且**只看 manifest 一个都发现不了**。
+
+| 你会看到 | 真正的原因 | 现在由谁拦 |
+| --- | --- | --- |
+| 标签是个红点，面板永远打不开 | `exports["."]` 指向了 CLI，加载器那一行没有插件可挂 | `root export` |
+| 插件装上了，应用从不加载它 | 声明了 `dsh.client`，但 `exports["./client"]` 不存在——宿主直接丢掉这一行 | `client declaration` |
+| 应用提示「第三方插件不支持」，把所有插件都禁用 | `apply()` 读了没声明的 `ctx.webServer`，cordis 不是返回 `undefined` 而是抛错 | `verify`（在一个没有任何服务的 ctx 上调用 `apply`） |
+| 标签注册成功，界面里却没有任何入口 | `sidebarRightTabs.register()` 注册的是**类型**，侧栏列的是 `tabs.guide()` 的返回 | testkit 的测试，不是 `doctor` |
+
+前三条是静态的：`doctor` 和 `verify` 不用开应用就能抓到。第四条是 UI 契约，必须把面板挂起来、检查注册出去的参数——那是 [`testkit`](#不用浏览器测面板) 的活。
+
 ## 安装要求
 
 - Node.js 18 或更新（CI 在 18/20/22 × ubuntu/macos/windows 上跑）。

package/lib/verify.mjs

@@ -39,8 +39,37 @@ function packTarball(dir, destination) {
  * What cordis hands a plugin that declares no `inject`: every undeclared
  * property read throws. A plain `{}` hides the bug this is looking for.
  */
+// cordis itself is present on every context — `ctx.inject`, `ctx.on`,
+// `ctx.effect` and the logger. What can be absent is the *services*.
+function cordisApi() {
+  const noop = () => () => {};
+  const base = {
+    inject: (list, callback) => {
+      // A declared service may still be absent when apply runs: record nothing,
+      // call nothing. That is exactly what the host does before a service mounts.
+      void list;
+      void callback;
+      return () => {};
+    },
+    on: noop,
+    effect: noop,
+    logger: () => {},
+    get: () => undefined,
+    set: () => {},
+    provide: noop,
+    reflect: { get: () => undefined, set: () => {}, provide: noop },
+  };
+  return base;
+}
+
+/** A context whose services have not mounted yet; reading one gives undefined. */
+function absentContext() {
+  return cordisApi();
+}
+
+/** A context that also enforces cordis's rule: an undeclared read throws. */
 function undeclaredContext() {
-  const base = { inject: undefined };
+  const base = cordisApi();
   return new Proxy(base, {
     get(target, key) {
       if (key in target) return target[key];
@@ -212,7 +241,7 @@ export async function verify({ dir, mount = true }) {
         faceProblems.push('the client module declares no inject list, so the loader calls apply() before its services exist');
       }
       try {
-        face.apply({});
+        face.apply(absentContext());
       } catch (error) {
         faceProblems.push(`apply() throws when the services are absent, which fails the web boot: ${error.message}`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Preflight, release and test DeepSeek Harness plugins: check a folder or any GitHub repository, wait for npm to actually serve the version, and keep the market index honest.",
   "type": "module",
   "bin": {