dsh-balance-plugin 0.2.0 → 0.2.1

package/PUBLISHING.md

@@ -1,45 +1,53 @@
 # Publishing dsh-balance-plugin
 
-Step-by-step release manual for the two official distribution channels (both are supported and can coexist).
+Release manual for the supported npm and GitHub Release tarball channels.
 
 ## Prerequisites
 
 - [npm](https://docs.npmjs.com/cli/) account, logged in: `npm whoami`
 - A GitHub account; the repository will be public.
 
-## 1. Create the GitHub repository
+## 1. Build and verify
 
-1. On GitHub, **New repository** → name `dsh-balance-plugin`, public.
-2. **Do not** initialize with README/.gitignore (this repo already has them).
-3. Add the local remote and push:
+```sh
+# from plugins/dsh-balance-plugin
+pnpm run build
+pnpm test
+pnpm pack --dry-run  # must contain lib/, cordis.patch.yml, README files, and LICENSE
+```
+
+In an isolated DSH `0.1.5-rc.1` or later profile, verify both installation and update behavior:
 
 ```sh
-cd ~/Documents/dsh-balance-plugin
-git remote add origin git@github.com:luokai-demo/dsh-plugins.git
-git push -u origin main
+dsh plugin --profile demo add ./dsh-balance-plugin-<version>.tgz
+dsh plugin --profile demo update dsh-balance-plugin
+dsh --profile demo --dump-config  # expect "# == dsh-balance-plugin"
 ```
 
-4. On the repository page: **About → Topics → add `dsh-plugin`** (the official discovery topic from DeepSeek Harness's README). Also consider `deepseek-harness`.
+Restart the Web profile and hard-refresh the browser to verify the authenticated balance readout.
 
 ## 2. Publish to npm
 
 ```sh
-# from ~/Documents/dsh-balance-plugin
 pnpm run build && pnpm test     # gates
-npm version patch                # bumps to 0.1.1, creates the git tag
+npm version patch                # creates the release version and git tag
 pnpm pack                        # inspect the tarball contents
 npm publish                      # publishes prebuilt lib/ — users install with zero friction
 git push && git push --tags
 ```
 
-npm is the **recommended** channel: users run `dsh plugin --profile <name> add dsh-balance-plugin` and get prebuilt code with no install-time build or permission prompt.
+npm is the **recommended** channel: users run `dsh plugin --profile <name> add dsh-balance-plugin` and get prebuilt code with no install-time build or permission prompt. Existing npm users upgrade with `dsh plugin --profile <name> update dsh-balance-plugin`.
 
-## 3. GitHub installs (optional, automatic once the repo exists)
+## 3. Publish a GitHub Release tarball
 
-Users can also install directly from GitHub. Two official caveats (from `docs/user/develop/basic/publish.md`):
+The package is in this monorepo's `plugins/` subdirectory, so `github:` package specs cannot target it. Publish the prebuilt tarball instead:
+
+```sh
+pnpm pack
+gh release create v<version> dsh-balance-plugin-<version>.tgz --title "dsh-balance-plugin <version>" --notes-file <notes-file>
+```
 
-- Git installs fetch **source**, not build output — the package ships a self-contained `prepare` script (`node scripts/build.mjs`, no project references), which pnpm runs after install;
-- pnpm ≥ 10 refuses to run git dependencies' `prepare` until the user opts in via `allowBuilds` in the profile's `pnpm-workspace.yaml`. Document this in your README (already present).
+Users install or replace a tarball release with `dsh plugin --profile <name> add ./dsh-balance-plugin-<version>.tgz`, then run `dsh --profile <name> --dump-config` and restart DSH.
 
 ## 4. Versioning and release notes
 
@@ -47,16 +55,7 @@ Users can also install directly from GitHub. Two official caveats (from `docs/us
 - Create a GitHub Release per tag with the changelog; reference the npm version.
 - Semantic versioning: `patch` for fixes, `minor` for features, `major` for breaking changes.
 
-## 5. Verification checklist (official inspection points)
-
-```sh
-# fresh install from the tarball
-dsh plugin --profile demo add ./dsh-balance-plugin-0.1.0.tgz
-dsh --profile demo --dump-config     # expect "# == dsh-balance-plugin" layer
-# then in the web profile with a real credential: the readout renders
-```
-
-## 6. Local development loop
+## 5. Local development loop
 
 ```sh
 pnpm install

package/README.md

@@ -2,6 +2,8 @@
 
 DeepSeek wallet balance at the sidebar foot — a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin.
 
+> **DeepSeek-only**: this plugin targets the DeepSeek platform exclusively — the official DeepSeek balance endpoint and `DEEPSEEK_API_KEY`. No other platforms or providers are supported.
+
 English | [中文](README.zh.md)
 
 Shows your DeepSeek account balance as a **card icon + amount** in the sidebar footer (beside Settings), tinted by how much is left. Refreshes when a conversation turn ends, on click, and on mount — no polling. When the amount changes, a signed delta (`+¥3.14` / `-¥1.97`) floats up and fades next to it — every spend (or top-up) is visible at a glance.
@@ -22,7 +24,7 @@ Shows your DeepSeek account balance as a **card icon + amount** in the sidebar f
 
 ## Install
 
-Requires a DeepSeek account credential. The plugin resolves `DEEPSEEK_API_KEY` through the harness credential seam (`~/.dsh/.credentials.yaml` or the environment), exactly like the official DeepSeek adapter.
+Requires DeepSeek Harness `0.1.5-rc.1` or later and a DeepSeek account credential. The plugin resolves `DEEPSEEK_API_KEY` through the optional harness credential service (`~/.dsh/.credentials.yaml`) or the environment.
 
 ### From npm (recommended)
 
@@ -40,6 +42,18 @@ dsh plugin --profile <name> add ./dsh-balance-plugin-<version>.tgz
 
 Note: the plugin lives in the `plugins/` subdirectory of the `dsh-plugins` monorepo, so `dsh plugin add github:...` cannot target it — use the tarball (or npm).
 
+### Update an existing install
+
+For npm installs, update the package in the same profile, confirm that its bundle layer remains active, then restart the Web server:
+
+```sh
+dsh plugin --profile <name> update dsh-balance-plugin
+dsh --profile <name> --dump-config  # expect a "# == dsh-balance-plugin" layer
+# restart dsh web, then hard-refresh the browser
+```
+
+`dsh plugin` forwards pnpm commands and reconciles the installed package's `dsh.bundle` declaration after a successful update. For a Release tarball, run `dsh plugin --profile <name> add ./dsh-balance-plugin-<version>.tgz` with the newer archive, then perform the same verification and restart.
+
 ## Configuration
 
 The plugin ships with sensible defaults; override via the bundle's plugin row:
@@ -59,7 +73,7 @@ The plugin ships with sensible defaults; override via the bundle's plugin row:
 
 | Half | What it does |
 |---|---|
-| **Host** (Node) | Registers `GET /dsh-balance` (the wallet readout as JSON) and `GET /dsh-balance/events` (an SSE stream). Listens on the harness's `session/event` broadcast and emits a `refresh` SSE event per `turn/end`. Resolves the credential **per request** through `ctx.credentials`, falling back to the environment — a changed key applies without a restart. |
+| **Host** (Node) | Registers authenticated `GET /dsh-balance` (the wallet readout as JSON) and `GET /dsh-balance/events` (an SSE stream). Each route passes the Harness browser-auth and Origin fence before reading a credential. It listens on `session/event` and emits `refresh` per `turn/end`, resolving credentials **per request** through the optional service before falling back to the environment. |
 | **Client** (browser) | Registers the `sidebar.footer.action` slot entry (the shell's reserved seat beside Settings; on the collapsed rail it stacks above the settings icon). Fetches the readout on mount, on `refresh` SSE events, and on click, with an in-flight guard. The card icon is self-contained (no dependency on the shell's icon library). |
 
 Position and interaction follow the shell's own design: the `sidebar.footer.action` hole is the official extension point for "optional actions beside Settings".
@@ -92,7 +106,7 @@ tests/              # node:test unit tests for balance-core
 ```sh
 pnpm install
 pnpm run build    # emits lib/index.js + lib/client.js
-pnpm test         # balance-core unit tests
+pnpm test         # balance-core, float, and host-route unit tests
 ```
 
 Local install check (official verification points):
@@ -107,7 +121,7 @@ dsh --profile demo --dump-config   # expect a "# == dsh-balance-plugin" layer
 Before publishing a new version:
 
 1. `pnpm run build` and `pnpm test` pass.
-2. Local install check above passes (`--dump-config` shows the layer; the web profile renders the readout with a real credential).
+2. Local install and `dsh plugin --profile demo update dsh-balance-plugin` both keep the `--dump-config` layer; the web profile renders the readout with a real credential.
 3. Version bumped (`npm version patch/minor/major`); git tag matches.
 4. `pnpm pack` — inspect the tarball: it must contain `lib/`, `cordis.patch.yml`, `README.md` (and nothing else heavy).
 5. `npm publish` — publishes prebuilt code, so users install with zero friction.

package/README.zh.md

@@ -2,6 +2,8 @@
 
 侧边栏底部的 DeepSeek 钱包余额——一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件。
 
+> **纯 DeepSeek**：本插件只针对 DeepSeek 平台——官方 DeepSeek 余额端点与 `DEEPSEEK_API_KEY`，不支持任何其他平台或服务商。
+
 [English](README.md) | 中文
 
 在侧边栏底部（设置按钮旁）以**信用卡图标 + 金额**显示你的 DeepSeek 账户余额，并按剩余额度着色。在对话结束时、点击时与挂载时刷新——无轮询。金额变动时，带符号的差额（`+¥3.14` / `-¥1.97`）会从余额旁上飘淡出——每次花费（或充值）都一目了然。
@@ -22,7 +24,7 @@
 
 ## 安装
 
-需要一个 DeepSeek 账户凭证。插件通过 harness 凭证接缝（`~/.dsh/.credentials.yaml` 或环境变量）解析 `DEEPSEEK_API_KEY`，与官方 DeepSeek 适配器一致。
+需要 DeepSeek Harness `0.1.5-rc.1` 或更高版本，以及一个 DeepSeek 账户凭证。插件通过可选的 harness 凭证服务（`~/.dsh/.credentials.yaml`）或环境变量解析 `DEEPSEEK_API_KEY`。
 
 ### 从 npm 安装（推荐）
 
@@ -40,6 +42,18 @@ dsh plugin --profile <名字> add ./dsh-balance-plugin-<版本>.tgz
 
 注意：插件位于 `dsh-plugins` monorepo 的 `plugins/` 子目录，`dsh plugin add github:...` 无法指向子目录——请使用 tarball（或 npm）。
 
+### 升级已有安装
+
+通过 npm 安装的版本，在同一个 profile 中升级包，确认 bundle 层仍处于启用状态，然后重启 Web 服务：
+
+```sh
+dsh plugin --profile <名字> update dsh-balance-plugin
+dsh --profile <名字> --dump-config  # 应出现 "# == dsh-balance-plugin" 层
+# 重启 dsh web，然后硬刷新浏览器
+```
+
+`dsh plugin` 会转发 pnpm 命令，并在成功升级后重新核对已安装包的 `dsh.bundle` 声明。GitHub Release tarball 则执行 `dsh plugin --profile <名字> add ./dsh-balance-plugin-<版本>.tgz` 安装新归档，再进行相同的验证与重启。
+
 ## 配置
 
 插件带合理默认值；可通过 bundle 的插件行覆盖：
@@ -59,7 +73,7 @@ dsh plugin --profile <名字> add ./dsh-balance-plugin-<版本>.tgz
 
 | 半面 | 做什么 |
 |---|---|
-| **宿主**（Node） | 注册 `GET /dsh-balance`（钱包读数 JSON）与 `GET /dsh-balance/events`（SSE 流）。监听 harness 的 `session/event` 广播，每个 `turn/end` 推送 `refresh` 事件。**每次请求**经 `ctx.credentials` 解析凭证并回退环境变量——改 key 无需重启。 |
+| **宿主**（Node） | 注册经认证的 `GET /dsh-balance`（钱包读数 JSON）与 `GET /dsh-balance/events`（SSE 流）。每个路由都会先通过 Harness 的浏览器身份与 Origin 栅栏，再读取凭证。监听 `session/event`，每个 `turn/end` 推送 `refresh`；**每次请求**经可选服务解析凭证，再回退环境变量。 |
 | **客户端**（浏览器） | 注册 `sidebar.footer.action` 插槽条目（shell 预留的设置旁座位；收起 rail 时堆叠在设置图标上方）。在挂载时、`refresh` SSE 事件与点击时抓取读数，带 in-flight 守卫。信用卡图标自包含（不依赖 shell 的图标库）。 |
 
 位置与交互遵循 shell 自身设计：`sidebar.footer.action` 是"设置旁可选操作"的官方扩展点。
@@ -86,13 +100,13 @@ src/
   index.ts          # 宿主插件：路由 + SSE + 轮次结束监听
   client.tsx        # 浏览器插件：侧边栏底部操作
 scripts/build.mjs   # esbuild：宿主 ESM + 浏览器 __ModuleLoader__ bundle
-tests/              # balance-core 的 node:test 单元测试
+tests/              # balance-core、float 与宿主路由的 node:test 单元测试
 ```
 
 ```sh
 pnpm install
 pnpm run build    # 生成 lib/index.js + lib/client.js
-pnpm test         # balance-core 单元测试
+pnpm test         # balance-core、float 与宿主路由单元测试
 ```
 
 本地安装检查（官方检验点）：
@@ -107,7 +121,7 @@ dsh --profile demo --dump-config   # 应出现 "# == dsh-balance-plugin" 层
 发布新版本前：
 
 1. `pnpm run build` 与 `pnpm test` 通过。
-2. 上述本地安装检查通过（`--dump-config` 显示层；web profile 用真实凭证渲染读数）。
+2. 上述本地安装与 `dsh plugin --profile demo update dsh-balance-plugin` 都通过；`--dump-config` 保留该层，且 Web profile 在真实凭证下能渲染读数。
 3. 版本已提升（`npm version patch/minor/major`）；git tag 对应。
 4. `pnpm pack`——检查 tarball：必须包含 `lib/`、`cordis.patch.yml`、`README.md`（别无其他大文件）。
 5. `npm publish`——发布预构建代码，用户零摩擦安装。

package/lib/index.js

@@ -98,13 +98,27 @@ async function fetchBalance(credentials, env, config) {
 
 // src/index.ts
 var name = "dsh-balance-plugin";
-var inject = ["webServer"];
+var inject = ["webServer", "connection"];
 var Config = Schema.object({
   apiKeyEnv: Schema.string().default("DEEPSEEK_API_KEY"),
   baseURL: Schema.string().default("https://api.deepseek.com"),
   timeoutMs: Schema.natural().min(1).max(12e4).default(12e3),
   lowBalanceThreshold: Schema.number().min(0).default(2)
 });
+function rejectUntrustedRequest(ctx, req, res) {
+  const connection = Reflect.get(ctx, "connection");
+  const status = connection.requestRejection(req);
+  if (status === void 0) return false;
+  res.statusCode = status;
+  res.end();
+  return true;
+}
+function rejectNonGetRequest(req, res) {
+  if (req.method === "GET") return false;
+  res.writeHead(405, { allow: "GET" });
+  res.end();
+  return true;
+}
 function apply(ctx, config) {
   const sseClients = /* @__PURE__ */ new Set();
   const broadcastRefresh = () => {
@@ -119,7 +133,8 @@ function apply(ctx, config) {
   const unregisterBalance = ctx.webServer.register({
     kind: "exact",
     path: "/dsh-balance",
-    handler: async (_req, res) => {
+    handler: async (req, res) => {
+      if (rejectUntrustedRequest(ctx, req, res) || rejectNonGetRequest(req, res)) return;
       const credentials = ctx.get("credentials");
       const resolver = credentials === void 0 ? void 0 : { resolve: (ref) => credentials.resolve(ref) };
       const readout = await fetchBalance(resolver, process.env, config);
@@ -136,6 +151,7 @@ function apply(ctx, config) {
     kind: "exact",
     path: "/dsh-balance/events",
     handler: (req, res) => {
+      if (rejectUntrustedRequest(ctx, req, res) || rejectNonGetRequest(req, res)) return;
       res.writeHead(200, {
         "content-type": "text/event-stream",
         "cache-control": "no-cache",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-balance-plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "DeepSeek wallet-balance readout at the sidebar foot: card icon + amount, status-tinted, refreshed on turn end and on click, with a floating delta animation on change",
   "type": "module",
   "main": "lib/index.js",
@@ -29,21 +29,14 @@
       ]
     }
   },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepare": "node scripts/build.mjs",
-    "test": "node --test tests/*.test.mjs"
-  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-credentials": "0.0.1-rc.5",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.0.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-credentials": "0.0.1-rc.5",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "@types/react": "^18.0.0",
     "esbuild": "^0.25.0",
     "react": "^18.0.0",
@@ -60,5 +53,9 @@
     "dsh-plugin",
     "balance",
     "wallet"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test tests/*.test.mjs"
+  }
+}