dsh-plugin-upgrader 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.0.1 — 2026-10-23
+
+- **Rewritten in TypeScript.** The whole project is now typed; `pnpm run typecheck`
+  covers both the host program and the tests.
+- **The browser half is split into modules** (`src/client/`) instead of one 1100-line
+  file: components, copy, styles, hooks, api and formatting each live on their own.
+  esbuild bundles them back into the single `lib/client.js` the DSH client loader
+  expects.
+- **A real build step.** `pnpm run build` runs `tsc` for the host half and `esbuild`
+  for the client half; `lib/` is the published artifact and is git-ignored.
+- **`pnpm run dev` watches both halves.** `tsc --watch` keeps `lib/index.js` and
+  `lib/host/**` current while the esbuild context rebuilds `lib/client.js`; a failed
+  client build keeps the last good file on disk instead of truncating it.
+- **pnpm replaces npm** as the package manager (`packageManager` is pinned);
+  `pnpm-lock.yaml` is the lockfile CI installs from.
+- `pnpm run check` now means typecheck + build + test, and CI runs it on every push.
+- **The row checkbox is drawn by the plugin.** `<input type="checkbox">` rendered
+  unchecked in the Harness window even when its `checked` state was set (the tick was
+  painted by the native control the app's WebView never drew), so selection looked
+  broken while the selection bar still counted the rows. The box is now a styled
+  element driven by `aria-checked`, and it looks identical on every platform.
+- **A 4.9× smaller package.** The published tarball drops from 196.5 KB to 50.4 KB
+  because `files` no longer ships `screenshots/` (130 KB of storefront images),
+  `screenshots.json`, `RELEASING.md` or `src/**/*.ts` — none of them are read at
+  runtime, and the sources are on GitHub. Sourcemaps *are* shipped now: every
+  `lib/*.js` ends with a `sourceMappingURL` comment, so leaving the maps out only
+  produced 404s in the consumer's devtools.
+
 ## 1.0.0
 
 First public release.

package/README.en.md

@@ -115,41 +115,72 @@ spinning forever.
 
 ```
 dsh-plugin-upgrader/
-├── src/
-│   ├── index.js          host: routes and job scheduling
-│   ├── client.js         browser: the Versions tab on the plugins.tab slot
-│   └── lib/
-│       ├── overview.js   assembles the overview payload
-│       ├── registry.js   packument fetch / shaping, GitHub tag lists
-│       ├── install.js    one install step plus enabled-state restore
-│       ├── bundle.js     bundle metadata (source kind, i18n fields, icons)
-│       ├── repo.js       repository URL normalisation
-│       ├── version.js    semver comparison, release links
-│       └── http.js       loopback guard, JSON read/write
+├── src/                  sources (TypeScript)
+│   ├── index.ts          host entry: route registration, job scheduling
+│   ├── host/             host-side logic (Node, no DOM)
+│   │   ├── overview.ts   assembles the overview payload
+│   │   ├── registry.ts   packument fetch / shaping, GitHub tag lists
+│   │   ├── install.ts    one install step plus enabled-state restore
+│   │   ├── bundle.ts     bundle metadata (source kind, i18n fields, icons)
+│   │   ├── repo.ts       repository URL normalisation
+│   │   ├── version.ts    semver comparison, release links
+│   │   ├── http.ts       loopback guard, JSON read/write
+│   │   └── manager.ts    the minimal host pluginManager type contract
+│   └── client/           browser side (modules, bundled into one file)
+│       ├── index.ts      createPlugin(require): slot registration entry
+│       ├── components/   Tab / PluginRow / VersionLine / JobPanel
+│       ├── copy.ts       zh / en strings
+│       ├── styles.ts     scoped CSS
+│       ├── hooks.ts      locale subscription, overview fetching
+│       ├── api.ts        fetch wrappers, job polling
+│       ├── format.ts     versions / dates / external links
+│       ├── env.ts        minimal window typings
+│       └── types.ts      payload types
+├── lib/                  build output (git-ignored, produced by `pnpm run build`)
+│   ├── index.js          host entry (tsc output)
+│   ├── host/*.js         host modules plus .d.ts
+│   └── client.js         the browser bundle, wrapped in __ModuleLoader__
+├── scripts/build.mjs     build: tsc for the host, esbuild for the client (--watch = dev)
+├── test/                 node:test unit tests (.ts, stripped natively by Node 24)
 ├── locale/               (reserved) language files
 ├── assets/icon.svg       icon
-├── test/                 node:test unit tests
 ├── cordis.patch.yml      bundle registration
 └── package.json
 ```
 
-`src/client.js` is a browser module loaded through `window.__ModuleLoader__`; it can
-only `require` modules the host provides (`react`), not local files, so it stays a
-single file.
+The browser half is split into `.ts` modules, but esbuild bundles it back into a
+single `lib/client.js` wrapped in `window.__ModuleLoader__.load({ id, factory(require) { … } })`.
+At runtime it can only `require` modules the host provides (`react`), not its own
+siblings, so the split happens in the sources only.
 
 ## Development
 
+Dependencies are managed with pnpm (`packageManager` is pinned in `package.json`,
+and CI uses pnpm too):
+
 ```bash
-npm test        # node:test unit tests (pure helpers: version compare, repo URLs, metadata)
-npm run check   # node --check syntax check
+pnpm install       # installs dependencies (runs prepare → one build)
+pnpm run dev       # watch src/, rebuild the host and the client on save
+pnpm run build     # tsc for the host + esbuild for the client → lib/
+pnpm run typecheck # tsc over src and test
+pnpm test          # node:test unit tests (.ts runs directly)
+pnpm run check     # all of the above (typecheck + build + test)
 ```
 
-The host half lives in `src/index.js` (a `webServer` prefix route at
-`/api/plugin-upgrader`), the browser half in `src/client.js` (registering the
+The host half lives in `src/index.ts` (a `webServer` prefix route at
+`/api/plugin-upgrader`), the browser half in `src/client/index.ts` (registering the
 `plugins.tab` slot).
 
-Reload the plugin after editing, no app restart needed: call
-`pluginManager.setBundleEnabled(name, false)` and then `setBundleEnabled(name, true)`.
+`pnpm run dev` runs two watchers side by side: `tsc --watch` owns `lib/index.js`
+and `lib/host/**`, esbuild owns `lib/client.js`, so neither overwrites the other.
+esbuild only strips types, it does not check them — run `pnpm run typecheck` after
+editing the browser half.
+
+Either way the profile's `link:` points at this directory but loads `lib/`, not
+`src/`, so the build has to run. `pnpm run dev` keeps the output current, but the
+plugin itself does **not** hot-reload — reload it without restarting the app by
+calling `pluginManager.setBundleEnabled(name, false)` and then
+`setBundleEnabled(name, true)`.
 
 ## License
 

package/README.md

@@ -99,39 +99,76 @@ dsh plugin --profile web add "$PWD"
 
 ```
 dsh-plugin-upgrader/
-├── src/
-│   ├── index.js          宿主端：路由注册、job 调度
-│   ├── client.js         浏览器端：plugins.tab 槽位的「版本」标签
-│   └── lib/
-│       ├── overview.js   组装 overview 载荷
-│       ├── registry.js   registry packument 拉取 / 裁剪、GitHub tag 列表
-│       ├── install.js    单步安装 + enabled 状态恢复
-│       ├── bundle.js     插件元数据（来源分类、多语言字段、图标）
-│       ├── repo.js       仓库 URL 归一化
-│       ├── version.js    semver 比较、发布页链接
-│       └── http.js       回环校验、JSON 读写
+├── src/                  源码（TypeScript）
+│   ├── index.ts          宿主端入口：路由注册、job 调度
+│   ├── host/             宿主端逻辑（Node，无 DOM）
+│   │   ├── overview.ts   组装 overview 载荷
+│   │   ├── registry.ts   registry packument 拉取 / 裁剪、GitHub tag 列表
+│   │   ├── install.ts    单步安装 + enabled 状态恢复
+│   │   ├── bundle.ts     插件元数据（来源分类、多语言字段、图标）
+│   │   ├── repo.ts       仓库 URL 归一化
+│   │   ├── version.ts    semver 比较、发布页链接
+│   │   ├── http.ts       回环校验、JSON 读写
+│   │   └── manager.ts    宿主 pluginManager 服务的最小类型契约
+│   └── client/           浏览器端（拆成模块，由 esbuild 打成一个文件）
+│       ├── index.ts      createPlugin(require)：槽位注册入口
+│       ├── components/   Tab / PluginRow / VersionLine / JobPanel
+│       ├── copy.ts       zh / en 文案
+│       ├── styles.ts     作用域 CSS
+│       ├── hooks.ts      locale 订阅、overview 拉取
+│       ├── api.ts        fetch 封装、job 轮询
+│       ├── format.ts     版本号 / 日期 / 外部链接
+│       ├── env.ts        window 上的最小类型声明
+│       └── types.ts      载荷类型
+├── lib/                  构建产物（git 忽略，`pnpm run build` 生成）
+│   ├── index.js          宿主端入口（tsc 输出）
+│   ├── host/*.js         宿主端模块 + .d.ts
+│   └── client.js         浏览器端单文件 bundle（含 __ModuleLoader__ 包装）
+├── scripts/build.mjs     构建脚本：tsc 编译宿主端 + esbuild 打包 client（加 --watch 即 dev）
+├── test/                 node:test 单元测试（.ts，Node 24 直接剥离类型）
 ├── locale/               （保留）语言包
 ├── assets/icon.svg       图标
-├── test/                 node:test 单元测试
 ├── cordis.patch.yml      bundle 注册
 └── package.json
 ```
 
-`src/client.js` 是浏览器模块，通过 `window.__ModuleLoader__` 加载，只能 `require('react')`
-这类由宿主提供的模块，不能 import 本地文件，所以它保持单文件。
+浏览器端虽然拆成了多个 `.ts` 模块，但最终由 esbuild 打成一个 `lib/client.js`，
+外面套上 `window.__ModuleLoader__.load({ id, factory(require) { … } })`。
+运行时它只能 `require('react')` 这类由宿主提供的模块，不能 require 自己的其它文件，
+所以「拆模块」只发生在源码层，产物仍然是单文件。
 
 ## 开发
 
+本项目用 pnpm 管理依赖（`package.json` 里钉了 `packageManager`，CI 也用 pnpm）：
+
 ```bash
-npm test        # node:test 单元测试（纯函数：版本比较、仓库 URL、元数据分类）
-npm run check   # node --check 语法检查
+pnpm install       # 安装依赖（会自动跑 prepare → 构建一次）
+pnpm run dev       # 监听 src/，宿主端和浏览器端改完即编译（Ctrl+C 停止）
+pnpm run build     # tsc 编译宿主端 + esbuild 打包 client → lib/
+pnpm run typecheck # tsc 检查 src 和 test
+pnpm test          # node:test 单元测试（.ts 直接运行）
+pnpm run check     # 以上全部（typecheck + build + test）
 ```
 
-宿主端在 `src/index.js`（`webServer` 前缀路由 `/api/plugin-upgrader`），
-浏览器端在 `src/client.js`（注册 `plugins.tab` 槽位）。
+宿主端在 `src/index.ts`（`webServer` 前缀路由 `/api/plugin-upgrader`），
+浏览器端在 `src/client/index.ts`（注册 `plugins.tab` 槽位）。
+
+`pnpm run dev` 会并行跑两个监听器：`tsc --watch` 负责 `lib/index.js` 和
+`lib/host/**`，esbuild 负责 `lib/client.js`，两者输出互不覆盖。注意 esbuild
+打包时会直接剥掉类型而不做检查，所以改浏览器端时顺手跑一次 `pnpm run typecheck`。
+
+改完代码后必须重新构建（profile 里的 `link:` 指向本目录，但加载的是 `lib/`，
+不是 `src/`）。`pnpm run dev` 已经替你重建了产物，但**插件本身不会热更新**——
+要让宿主重新加载本插件，无需重启应用：先 `pluginManager.setBundleEnabled(name, false)`
+再 `setBundleEnabled(name, true)`。
+
+## 发布
 
-改完代码后让宿主重新加载本插件即可，无需重启应用：
-先 `pluginManager.setBundleEnabled(name, false)` 再 `setBundleEnabled(name, true)`。
+见 [RELEASING.md](./RELEASING.md)。首次手动发一次，之后打 `v*` tag 由 CI 通过 npm trusted publishing 自动发布：
+
+```bash
+pnpm publish --access public   # 仅首次
+```
 
 ## 许可