dsh-plugin-toolkit 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.9.5
+
+- The panel reports its own failures. When a row fails to activate the app shows
+  one red dot and no text, so the bundle now posts what happened to
+  `POST /toolkit/report`; the host appends it to `~/.dsh/toolkit-client-report.ndjson`.
+  Every stage is reported — `apply`, `no-inject`, `no-sidebar`, `tab-registered`,
+  `tab-failed` — so "did it run at all" is answerable without a debugger.
+- The failure that motivated it: `ctx.inject` callbacks run *after* `apply()`
+  returns, so the guards added in 0.9.4 could not see a throwing registration and
+  the row still ended up failed. The callback body is now guarded and reported.
+- The client module no longer sets `name` on its face; it is the package's name
+  either way, and the face now matches the shape that works.
+- `mountClient` accepts a `host`, so a test can hand the panel a service that
+  throws on purpose. Without it "the service threw" — the failure mode that costs
+  the most to debug in the app — was untestable.
+- `README.zh.md`: the whole tour in Chinese, linked from the top of the README.
+  The install examples now say `@latest` instead of a version that goes stale.
+
 ## 0.9.4
 
 - The client module now declares `inject: ['slots', 'locale']` and guards every

package/README.md

@@ -2,12 +2,14 @@
 
 ![dsh-plugin-toolkit](docs/card.png)
 
+English · [中文](./README.zh.md)
+
 Everything a [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugin needs between `init` and a version the market index accepts: scaffolding, a test harness for the client bundle, a way to see a change without restarting the app, and a release that does not depend on remembering fourteen steps.
 
 ```sh
-npx dsh-plugin-toolkit@0.7.0 init ./my-panel --name my-panel   # a plugin that already passes the checks
-npx dsh-plugin-toolkit@0.7.0 verify .                          # pack it, install the tarball, mount the panel
-npx dsh-plugin-toolkit@0.7.0 release --pr --merge              # tag, wait for npm, update the index, open and merge the PR
+npx dsh-plugin-toolkit@latest init ./my-panel --name my-panel   # a plugin that already passes the checks
+npx dsh-plugin-toolkit@latest verify .                          # pack it, install the tarball, mount the panel
+npx dsh-plugin-toolkit@latest release --pr --merge              # tag, wait for npm, update the index, open and merge the PR
 ```
 
 ## Three paths
@@ -32,8 +34,8 @@ $ dsh plugin add dsh-plugin-toolkit
 [`init`](#start-from-a-plugin-that-already-passes) writes the files whose absence shows up as a failed first publish — `engines.dsh`, the patch file, a `files` list that ships the code, a client bundle, a test for it, and the CI that runs both. `doctor` then checks the same things without writing anything, and [`verify`](#prove-the-tarball-works-not-just-the-repository) checks the tarball instead of the working copy.
 
 ```sh
-npx dsh-plugin-toolkit@0.7.0 init ./my-panel --name my-panel
-cd my-panel && npm install && npm test && npx dsh-plugin-toolkit@0.7.0 doctor .
+npx dsh-plugin-toolkit@latest init ./my-panel --name my-panel
+cd my-panel && npm install && npm test && npx dsh-plugin-toolkit@latest doctor .
 ```
 
 ### 2. Develop a panel
@@ -41,8 +43,8 @@ cd my-panel && npm install && npm test && npx dsh-plugin-toolkit@0.7.0 doctor .
 A plugin's client code is one file that calls `window.__ModuleLoader__.load({factory})` — there is no module to import, so the usual React test setup does not apply. [`testkit`](#test-a-panel-without-a-browser) supplies the missing half, and [`dev`](#edit-a-plugin-that-is-already-installed) pushes a rebuilt bundle into the running app.
 
 ```sh
-npx dsh-plugin-toolkit@0.7.0 mount ./client.js     # what a user would see, without the app
-npx dsh-plugin-toolkit@0.7.0 dev . --host http://127.0.0.1:54133
+npx dsh-plugin-toolkit@latest mount ./client.js     # what a user would see, without the app
+npx dsh-plugin-toolkit@latest dev . --host http://127.0.0.1:54133
 ```
 
 ### 3. Ship a version
@@ -50,8 +52,8 @@ npx dsh-plugin-toolkit@0.7.0 dev . --host http://127.0.0.1:54133
 `verify` first (it is the only check that reads the tarball), then `release`, which tags, waits for the registry, writes the index entry with the publish time the registry reports, and — with `--pr --merge` — opens and merges the pull request.
 
 ```sh
-npx dsh-plugin-toolkit@0.7.0 verify .
-npx dsh-plugin-toolkit@0.7.0 release . --pr --merge
+npx dsh-plugin-toolkit@latest verify .
+npx dsh-plugin-toolkit@latest release . --pr --merge
 ```
 
 ## Why this exists
@@ -72,7 +74,7 @@ Releasing one plugin fifteen times taught me three things the ecosystem's toolin
 ## Start from a plugin that already passes
 
 ```sh
-$ npx dsh-plugin-toolkit@0.7.0 init ./my-panel --name my-panel --title "My panel"
+$ npx dsh-plugin-toolkit@latest init ./my-panel --name my-panel --title "My panel"
 created 8 file(s) in /Users/you/my-panel
   .github/workflows/ci.yml
   .gitignore

package/README.zh.md

@@ -0,0 +1,158 @@
+# dsh-plugin-toolkit
+
+![dsh-plugin-toolkit](docs/card.png)
+
+[English](./README.md) · 中文
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/dsh) 插件从 `init` 到被市场索引接受之间需要的一切：脚手架、客户端 bundle 的测试台、不重启应用就能看到改动的方法，以及一条不用背十四个步骤的发布流程。
+
+```sh
+npx dsh-plugin-toolkit@latest init ./my-panel --name my-panel   # 生成一个已经能通过检查的插件
+npx dsh-plugin-toolkit@latest verify .                          # 打包、安装 tarball、真的把面板挂起来
+npx dsh-plugin-toolkit@latest release --pr --merge              # 打 tag、等 npm、更新索引、开 PR 并合并
+```
+
+## 三条路径
+
+| 你是谁 | 从这里开始 | 然后 |
+| --- | --- | --- |
+| 第一次写插件 | `init` | `doctor`、`verify` |
+| 改一个已经装上的面板 | `dev` | `mount`、testkit、`audit` |
+| 要发一个版本 | `verify` | `release`、`index` |
+
+## 为什么会有这个工具
+
+我发布自己第一个面板插件的那天，同一个错误在四个地方各出现一次，而且每次的报错都指向别处：
+
+1. `package.json` 里 `exports["."]` 指向 CLI，插件装上了，加载器那行**什么都 apply 不到**；
+2. `files` 忘了 `client.js`，`npm pack` 出来的包里没有面板代码，`doctor` 读工作副本看不出来；
+3. 声明了 `dsh.client` 却没有 `exports["./client"]`，宿主直接把这一行丢掉，界面上只留一个红点「异常」，没有任何文字；
+4. 客户端 apply 里没保护的 `ctx.locale.register(...)` 在服务就绪前抛错，**整个 web boot 失败**，应用把这判成「第三方插件不支持」并关掉所有插件。
+
+每一条都能在发布前被机器拦住，所以每一条现在都是一项检查。这些检查对着**宿主的解析代码**写，而不是对着文件约定写——差别就是 `verify` 报 `mounted the panel` 而真实宿主什么都不加载。
+
+## 安装要求
+
+- Node.js 18 或更新（CI 在 18/20/22 × ubuntu/macos/windows 上跑）。
+- 要发布时需要一个能写 `market/index.json` 的仓库和 `gh`（已登录）。
+
+## 从一个已经能通过检查的插件开始
+
+```sh
+npx dsh-plugin-toolkit@latest init ./my-panel --name my-panel
+cd my-panel && npm install && npm test
+```
+
+生成的项目里已经有了这些容易被忘掉的东西：
+
+- `main` / `exports[".""]` 指向插件本体（`index.js`，导出 `apply`）；
+- `exports["./client"]` 指向 `client.js`（**没有它宿主不服务这个 bundle**）；
+- `dsh.client = { platform: "web", immediately: true }` 与 `dsh.bundle.patch`；
+- `files` 覆盖上面每一个路径；
+- 一份 `node --test` 用例和一个钉住本工具版本的 CI 工作流。
+
+版本号取自当前运行的 CLI 自身，所以脚手架不会落后于你正在读的文档。
+
+## 不用浏览器测面板
+
+```js
+import { createFetch, expectSnapshot, mountClient } from 'dsh-plugin-toolkit/testkit';
+
+const panel = await mountClient({
+  file: 'client.js',
+  copy: { en: {} },
+  fetch: createFetch({ '/toolkit/check': { body: { ok: true, checks: [] } } }),
+});
+
+await panel.type('.tk-input', '/tmp/plugin');
+await panel.click('.tk-button');
+console.log(panel.text());
+await panel.unmount();
+```
+
+`mountClient` 用 jsdom 加载真实的单文件 bundle、注入宿主服务、把组件真的渲染出来。它提供 `type` / `click` / `press`（都返回 Promise）、`text()`、`query` / `queryAll` / `must`，以及 `aria(selector)` / `expectAria(selector, expected)`——后者让「读屏器看到的是什么」变成断言，而不是靠选择器猜。
+
+### 留一份视觉基线
+
+```js
+await expectSnapshot(panel, { name: 'empty' });
+```
+
+第一次运行写入 `test/__snapshots__/empty.html` 与 `.aria.txt`；之后每次比较，差异会打印出来。
+
+## 看看装了什么，以及应用到底加载了没有
+
+```sh
+npx dsh-plugin-toolkit@latest audit --host http://127.0.0.1:54133
+```
+
+它扫描 `~/.dsh/profiles/*/node_modules` 里所有声明了 `dsh` 的包，对每个跑 `doctor`，再从宿主的 `/plugins/events` 读取「应用真的加载了它吗」。输出把两类问题分开：
+
+- **hard**：`root export` 没有 `apply`、`exports["./client"]` 缺失、patch 形状不对——这些会让插件不工作；
+- **advisory**：缺 `engines.dsh`、README 没有 Requirements 段——市场索引要这些，加载器不读。
+
+`7 installed plugin(s) are not in the running app` 和 `13 … not ready for the market index` 是两件事，混着数会让人去修根本不影响使用的东西。
+
+## 改一个已经装上的插件
+
+```sh
+npx dsh-plugin-toolkit@latest dev ./my-plugin --host http://127.0.0.1:54133
+```
+
+它监听源码，把改动复制进 profile 的 `node_modules`，然后在宿主的 `/plugins/events` SSE 上等一帧 `rebuilt` 确认——只有真的重载了才算成功。如果预览显示 `the running app has not loaded <id>`，那是插件没被加载，重启一次应用即可，不是 dev 的问题。
+
+## 在 CI 里用
+
+```yaml
+- uses: WJDdidi-1/dsh-plugin-toolkit@v1
+  with:
+    dir: .
+    version: 0.9.5
+```
+
+默认跑 `verify`：打包、把 tarball 装进临时目录、import 根导出断言它有 `apply`、用裸 ctx 调一次 `apply({})` 确认服务缺失时降级而不是抛错、最后把面板挂起来。`doctor` 在读工作副本，`verify` 在读**用户真正会装到的东西**。
+
+## `doctor` 检查什么
+
+| 检查 | 拦住的是 |
+| --- | --- |
+| manifest | 没有 `name` / `version` / `engines.dsh` |
+| root export | `exports["."]` 指向 CLI，加载器那行没有插件可 apply |
+| client entry | 找不到 bundle，或 `dsh.client` 与 `exports["./client"]` 不一致 |
+| client declaration | `platform` 不是 `web`、缺 `exports["./client"]`、指向的文件不存在 |
+| files list | `npm pack` 不会带上 manifest 指到的路径 |
+| patch | `cordis.patch.yml` 不是唯一一条 `- insert:` |
+| readme | 没有 Requirements 段（advisory，市场索引要） |
+
+`dsh-plugin-toolkit doctor .` 的退出码只由 hard 项决定。
+
+## 面板不出现的时候
+
+按顺序查这五件事：
+
+1. **重启应用**——客户端 bundle 只在启动时加载；
+2. 根导出是不是插件：`node -e "import('dsh-plugin-toolkit').then(m => console.log(typeof m.apply))"` 应为 `function`；
+3. tarball 里有没有它：`npx dsh-plugin-toolkit verify .`；
+4. `cordis.patch.yml` 是不是恰好一条 `- insert:`，`name` 与包名一致；
+5. 面板自己有没有报错：`~/.dsh/toolkit-client-report.ndjson`（本插件的面板把激活失败写在这里，因为界面只有一个红点）。
+
+## `release` 做什么
+
+1. 预检版本、`engines.dsh`、README Requirements；
+2. `git tag plugin-vX.Y.Z && git push origin plugin-vX.Y.Z`（`--publish` 时接着 `npm publish`）；
+3. 轮询 npm registry 直到这个版本真的可下载（传播通常 2–8 分钟，`npm view` 有缓存，直接读 `versions`）；
+4. 把 `market/index.json` 里该插件改成新版本 + 真实 `publishTimestamp`；
+5. 在索引所在的仓库开 PR，`--merge` 时等 CI 全绿后 squash 合并；
+6. 从 raw URL 复核线上索引确实变了。
+
+索引在别人的仓库里时用 `--market <dir>`，它会对着那个目录做第 4–6 步。
+
+## 还没有的
+
+- 不做插件市场本身，也不代替 `dsh plugin add`；
+- 不校验你的面板长得好不好看——视觉基线只负责「和上次一样」；
+- Windows 上的路径与 `npm.cmd` 有专门的测试，但没有 Windows 实机手工验证。
+
+## 许可
+
+Apache-2.0。

package/client.js

@@ -136,44 +136,99 @@ window.__ModuleLoader__.load({
           : null);
     }
 
+    function describe(error) {
+      if (error === undefined || error === null) return 'unknown';
+      const text = error.stack !== undefined ? String(error.stack) : String(error.message !== undefined ? error.message : error);
+      return text.split('\n').slice(0, 3).join(' | ');
+    }
+
+    /**
+     * The panel's own crash reporter. When the row fails to activate the app
+     * shows one red dot and no text, and the bundle has no console anyone can
+     * read, so it posts what happened and the host appends it to
+     * `~/.dsh/toolkit-client-report.ndjson`.
+     */
+    function report(stage, detail) {
+      try {
+        if (typeof fetch !== 'function') return;
+        const body = JSON.stringify({
+          stage,
+          message: describe(detail),
+          services: ['slots', 'locale', 'sidebarRightTabs', 'sidebarRight'],
+        });
+        fetch('/toolkit/report', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body,
+        }).catch(() => {});
+      } catch {
+        // Reporting is best effort; it never changes the outcome.
+      }
+    }
+
     function apply(ctx) {
       // A panel that cannot find its services must degrade, not fail the boot:
       // an exception here fails the whole web boot and takes every other plugin
       // down with it. Every service below is optional for that reason.
+      const has = (name) => {
+        try {
+          return ctx[name] !== undefined && ctx[name] !== null;
+        } catch {
+          return false;
+        }
+      };
+      report('apply', `services slots=${String(has('slots'))} locale=${String(has('locale'))} inject=${typeof ctx.inject}`);
       try {
         injectStyles(typeof document === 'undefined' ? undefined : document);
-      } catch {
+      } catch (error) {
         // No document: the styles are cosmetic.
+        report('styles', error);
       }
       try {
         if (ctx.locale !== undefined && typeof ctx.locale.register === 'function') ctx.locale.register(NS, COPY);
-      } catch {
+      } catch (error) {
         // The panel keeps its English strings.
+        report('locale', error);
       }
       try {
-        if (typeof ctx.inject !== 'function') return;
+        if (typeof ctx.inject !== 'function') {
+          report('no-inject', 'ctx.inject is not a function');
+          return;
+        }
         ctx.inject(['sidebarRightTabs', 'sidebarRight'], (tabCtx) => {
-          if (tabCtx === undefined || tabCtx.slots === undefined || tabCtx.sidebarRightTabs === undefined) return;
-          tabCtx.effect(() => tabCtx.slots.inject('sidebar.right.pane.tab', () => tabCtx.slots.register({
-            name: 'sidebar.right.pane.tab',
-            key: NS,
-            locale: NS,
-          }, Panel)));
-          tabCtx.effect(() => tabCtx.sidebarRightTabs.register({
-            id: NS,
-            kind: KIND,
-            priority: 'extension',
-            title: () => 'Plugin doctor',
-          }));
+          // Failures inside this callback happen after apply() returned, so the
+          // guards above do not cover them — this try/catch is the one that
+          // decides whether the row lands in "failed".
+          try {
+            if (tabCtx === undefined || tabCtx.slots === undefined || tabCtx.sidebarRightTabs === undefined) {
+              report('no-sidebar', `tabCtx slots=${String(tabCtx !== undefined && tabCtx.slots !== undefined)} sidebarRightTabs=${String(tabCtx !== undefined && tabCtx.sidebarRightTabs !== undefined)}`);
+              return;
+            }
+            tabCtx.effect(() => tabCtx.slots.inject('sidebar.right.pane.tab', () => tabCtx.slots.register({
+              name: 'sidebar.right.pane.tab',
+              key: NS,
+              locale: NS,
+            }, Panel)));
+            tabCtx.effect(() => tabCtx.sidebarRightTabs.register({
+              id: NS,
+              kind: KIND,
+              priority: 'extension',
+              title: () => 'Plugin doctor',
+            }));
+            report('tab-registered', `kind=${KIND}`);
+          } catch (error) {
+            report('tab-failed', error);
+          }
         });
-      } catch {
+      } catch (error) {
         // No sidebar: the plugin still loads, it just has no place to show.
+        report('inject', error);
       }
     }
 
     // The services the tab body reads. Declaring them lets the loader wait for
     // them instead of calling apply() before they exist.
-    module.exports = { inject: ['slots', 'locale'], apply, name: 'dsh-plugin-toolkit' };
+    module.exports = { inject: ['slots', 'locale'], apply };
     return module.exports;
   },
 });

package/index.js

@@ -7,6 +7,7 @@
  * the command that fixes it. Nothing here writes to the workspace.
  */
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import { doctor } from './lib/doctor.mjs';
@@ -78,7 +79,56 @@ export async function checkPlugin(dir) {
   return { ok: checks.every((entry) => entry.ok === true), dir: target, checks };
 }
 
+/**
+ * The client half cannot see the host console, and a panel that fails to
+ * activate shows up as one red dot — no message, nowhere to look. This route is
+ * the plugin's own crash reporter: the bundle posts what happened, the host
+ * appends it to `~/.dsh/toolkit-client-report.ndjson`.
+ */
+function appendReport(entry) {
+  try {
+    const file = path.join(os.homedir(), '.dsh', 'toolkit-client-report.ndjson');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(entry)}\n`);
+  } catch {
+    // A report that fails to write must not become a second failure.
+  }
+}
+
+function clip(value, limit) {
+  if (typeof value !== 'string') return null;
+  return value.length > limit ? `${value.slice(0, limit)}…` : value;
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 8192) return null;
+    chunks.push(chunk);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
 export function apply(ctx) {
+  const reportHandler = async (req, res) => {
+    if (req.method !== 'POST') return sendJson(res, 405, { error: 'method-not-allowed' });
+    const body = await readBody(req);
+    if (body === null || typeof body !== 'object') return sendJson(res, 400, { error: 'bad-report' });
+    appendReport({
+      at: new Date().toISOString(),
+      stage: clip(body.stage, 60),
+      message: clip(body.message, 500),
+      services: Array.isArray(body.services) ? body.services.slice(0, 20).map((name) => clip(String(name), 60)) : [],
+    });
+    return sendJson(res, 200, { ok: true });
+  };
+
   const checkHandler = async (req, res) => {
     if (req.method !== 'GET') return sendJson(res, 405, { error: 'method-not-allowed' });
     if (sameOrigin(req) === false) return sendJson(res, 403, { error: 'cross-origin' });
@@ -96,6 +146,7 @@ export function apply(ctx) {
     const server = serviceCtx !== null && serviceCtx !== undefined ? serviceCtx.webServer : undefined;
     if (server === null || server === undefined || typeof server.register !== 'function') return;
     server.register({ kind: 'exact', path: '/toolkit/check', handler: checkHandler });
+    server.register({ kind: 'exact', path: '/toolkit/report', handler: reportHandler });
     installed = true;
   };
 

package/lib/testkit/mount.mjs

@@ -65,7 +65,10 @@ export async function mountClient(options) {
     'react/jsx-dev-runtime': jsxDevRuntime,
   };
 
-  const host = createHost({ locale: copy, fetch: fetchImpl, surface });
+  // A test that needs a host which fails on purpose passes its own: the default
+  // host never throws, and "the service threw" is the failure mode that costs
+  // the most to debug in the real app.
+  const host = options.host ?? createHost({ locale: copy, fetch: fetchImpl, surface });
   // The panel calls the browser's fetch, not a service, so the stub has to be
   // the global one for the duration of the mount.
   const previousFetch = globalThis.fetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "client.js",
     "cordis.patch.yml",
     "README.md",
+    "README.zh.md",
     "LICENSE",
     "CHANGELOG.md"
   ],