dsh-update-status 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.0 — 2026-09-10
+
+- Added a static DeepSeek Harness Web Cordis plugin with a read-only Host update-status service.
+- Added npm `latest`, `next`, and `alpha` dist-tag discovery through one HTTPS-allowlisted, timeout-bounded registry request.
+- Added a six-hour process cache, single-flight behavior, prerelease-aware SemVer comparison, and failed-refresh fallback.
+- Added `sidebar.brand.name` replacement (`DeepSeek + status Badge`) without replacing the official fish mark.
+- Added a collapsed-rail `sidebar.footer.action` fallback.
+- Added a modal top-layer detail panel and safe-area-aware mobile bottom sheet that stays above the sidebar drawer.
+- Added persisted channel selection in Settings and directly in the detail panel.
+- Added meaningful-channel filtering: redundant same-version candidates are hidden and duplicate releases favor `latest`.
+- Added verified/unverified compatibility labels and channel-specific copy-only commands.
+- Added automated tests for Host RPC, registry parsing, caching, channel projection, client stores, SemVer, and channel presentation.
+
+No package-manager execution, automatic installation, restart, rollback, release download, or in-place file replacement is implemented.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-update-status contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+<h1 align="center">DSH Update Status</h1>
+
+<p align="center">A read-only version badge and release-channel guide for the DeepSeek Harness Web sidebar.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-update-status"><img src="https://img.shields.io/npm/v/dsh-update-status?label=npm&color=CB3837" alt="npm version"></a>
+  <a href="https://github.com/idoall/dsh-update-status/actions/workflows/ci.yml"><img src="https://github.com/idoall/dsh-update-status/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0F172A" alt="MIT"></a>
+</p>
+
+<p align="center">English | <a href="README.zh.md">中文</a></p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#security-boundary">Security</a> ·
+  <a href="#uninstall">Uninstall</a> ·
+  <a href="docs/RELEASING.md">Release guide</a>
+</p>
+
+> DSH Update Status is a community plugin for DeepSeek Harness. It does not modify DSH core and it never installs, restarts, rolls back, downloads, or replaces DSH files.
+
+It replaces only the expanded sidebar wordmark text with `DeepSeek` plus a compact version badge while leaving the official fish mark untouched. Tap the badge to inspect npm release channels, compatibility status, and a copy-only command for the selected channel.
+
+<p align="center">
+  <img src="./assets/update-panel.png" width="500" alt="DSH Update Status panel showing the current stable release, an alpha preview, compatibility labels, and a copy-only upgrade command">
+</p>
+
+## Features
+
+- **Visible version status** — shows the running DSH version in the expanded sidebar and a fallback action in the collapsed rail.
+- **Stable and preview discovery** — reads npm dist-tags `latest`, `next`, and `alpha` in one registry request; `latest` is the default.
+- **Useful choices only** — hides a non-selected candidate when it equals the running version, and collapses duplicate releases in favor of `latest`.
+- **In-panel channel selection** — select a meaningful stable, candidate, or preview release directly in the panel; the preference is stored by the DSH Host.
+- **Compatibility labels** — explicitly verified versions are marked verified; unknown preview compatibility is marked unverified rather than claimed safe.
+- **Copy-only guidance** — generates an installation-kind-aware `@latest`, `@next`, or `@alpha` command but never executes it.
+- **Cache without polling** — one Host check on mount, a configurable 30–1,440 minute cache, single-flight registry access, and no frontend polling. Only the Check for updates button bypasses the cache.
+- **Mobile-safe panel** — uses a modal browser top layer so the scrollable, safe-area-aware bottom sheet stays above the DSH drawer.
+
+## Install
+
+Requirements:
+
+- DeepSeek Harness with the Web profile
+- Node.js 20 or newer
+- Verified DSH release: `0.1.2-rc.1`
+
+With an installed `dsh` command:
+
+```sh
+dsh plugin --profile web add dsh-update-status@latest
+```
+
+From a DeepSeek Harness source checkout:
+
+```sh
+corepack enable
+pnpm install
+pnpm dsh plugin --profile web add dsh-update-status@latest
+```
+
+Restart the existing DSH process after installation, then refresh its Web GUI. Do not start a second Web server for this plugin.
+
+Local development link:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run build
+dsh plugin --profile web add "link:$(pwd)"
+```
+
+## Usage
+
+1. Open the DSH sidebar drawer. The official fish remains in place; the name row shows `DeepSeek` plus the current version badge.
+2. Tap the badge. The update panel opens without triggering the parent New Session action.
+3. Review meaningful channels. If `next` points to the same release as the running/stable version, it is intentionally omitted.
+4. Select `alpha` or another available channel if you want to evaluate it. An unverified preview remains clearly marked.
+5. Copy the generated command and run it yourself in a terminal on the computer hosting DSH.
+6. Restart DSH yourself after the package-manager command completes.
+
+Example commands generated for a global install:
+
+```sh
+npm install -g @deepseek-ai/dsh@latest
+npm install -g @deepseek-ai/dsh@next
+npm install -g @deepseek-ai/dsh@alpha
+```
+
+The plugin displays one command that matches the detected installation kind and selected channel. It does not run these commands.
+
+## Release channels
+
+| Channel | Purpose | Compatibility treatment |
+| --- | --- | --- |
+| `latest` | Default stable/candidate recommended by the DSH npm package | Verified only when explicitly declared by this plugin |
+| `next` | Candidate release when it differs meaningfully from the running/stable release | May be unverified |
+| `alpha` | Opt-in preview for early evaluation | Unverified unless explicitly declared otherwise |
+
+The plugin honors npm dist-tags. It does not pick the numerically greatest version from registry history.
+
+## Compatibility
+
+| Plugin | Verified DeepSeek Harness |
+| --- | --- |
+| `0.1.0` | `0.1.2-rc.1` |
+
+A newer DSH version is not automatically declared compatible. Verify it manually first. If the plugin is incompatible, disable or uninstall it rather than patching DSH core.
+
+## Configuration
+
+| Option | Default | Range / behavior |
+| --- | --- | --- |
+| `cacheTtlMinutes` | `360` | 30–1,440 minutes; expires only for the next on-demand read, never a background timer |
+| `channel` | `latest` | `latest`, `next`, or `alpha` |
+| `sidebarEnabled` | `true` | Hides only this plugin's sidebar entry |
+
+**Settings → Version & updates** lets the local operator hide the plugin's sidebar entry and select a release channel. The panel also supports direct channel selection and a cache-duration input. Changing the duration does not issue a request; only a later normal read can refresh an expired cache, while **Check for updates** always performs an immediate manual refresh.
+
+## Security boundary
+
+- Registry access is limited to HTTPS `registry.npmjs.org`; redirects are rejected.
+- The Host returns ordinary JSON over the authenticated DSH Connection RPC channel.
+- There is no public Remote Service and no model Tool.
+- No package-manager process is spawned by plugin code.
+- `canApplyInPlace` is always `false`.
+- There is no Update now button, automatic install, restart, rollback, or release-file replacement.
+- A failed refresh retains the last good cache and displays a warning; a cold failure still shows the local version.
+
+## Uninstall
+
+```sh
+dsh plugin --profile web remove dsh-update-status
+```
+
+Restart DSH and refresh the Web GUI. If desired, remove the `dsh-update-status` settings namespace from `~/.dsh/settings.yaml` after uninstalling.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run test
+pnpm run build
+pnpm pack --dry-run
+```
+
+Release tags use npm Trusted Publishing with GitHub OIDC. See [docs/RELEASING.md](docs/RELEASING.md) to configure npm’s Trusted Publisher once, then push a matching `vX.Y.Z` tag; no long-lived npm token is stored in this repository.
+
+MIT. See [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,149 @@
+<h1 align="center">DSH Update Status</h1>
+
+<p align="center">DeepSeek Harness Web 侧栏中的只读版本状态 Badge 与发布通道指南。</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-update-status"><img src="https://img.shields.io/npm/v/dsh-update-status?label=npm&color=CB3837" alt="npm 版本"></a>
+  <a href="https://github.com/idoall/dsh-update-status/actions/workflows/ci.yml"><img src="https://github.com/idoall/dsh-update-status/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0F172A" alt="MIT"></a>
+</p>
+
+<p align="center"><a href="README.md">English</a> | 中文</p>
+
+<p align="center">
+  <a href="#功能">功能</a> ·
+  <a href="#安装">安装</a> ·
+  <a href="#使用">使用</a> ·
+  <a href="#安全边界">安全边界</a> ·
+  <a href="#卸载">卸载</a> ·
+  <a href="docs/RELEASING.md">发布指南</a>
+</p>
+
+> DSH Update Status 是 DeepSeek Harness 社区插件。它不修改 DSH 核心，也绝不会安装、重启、回滚、下载或替换 DSH 文件。
+
+插件只把展开侧栏中的完整名称文字换成 `DeepSeek + 版本 Badge`，官方鱼标保持不变。点击 Badge 可查看 npm 发布通道、兼容性状态，以及与所选通道对应的“仅复制”命令。
+
+<p align="center">
+  <img src="./assets/update-panel.png" width="500" alt="DSH Update Status 面板：当前稳定版、alpha 预览版、兼容性标签和仅复制的升级命令">
+</p>
+
+## 功能
+
+- **侧栏版本状态**：展开侧栏显示当前 DSH 版本，收起轨道提供状态入口。
+- **稳定版与预览版发现**：一次 registry 请求读取 npm dist-tags `latest`、`next`、`alpha`，默认选择 `latest`。
+- **只展示有意义的选择**：非当前候选与运行版本相同时隐藏；多个通道指向同一版本时优先保留 `latest`。
+- **弹窗内直接选择通道**：可直接选择有价值的稳定版、候选版或预览版；偏好由 DSH Host 持久化。
+- **兼容性标识**：明确验证过的版本显示“已验证兼容”；未知预览版显示“尚未验证兼容”，不冒充安全升级。
+- **仅复制命令**：根据安装来源和通道生成 `@latest`、`@next` 或 `@alpha` 命令，但从不执行。
+- **缓存但不轮询**：Host 挂载时检查一次，缓存可设为 30–1,440 分钟并合并并发请求；前端没有轮询，只有“检查更新”按钮绕过缓存。
+- **移动端可靠**：详情使用浏览器 modal top layer；底部 sheet 可滚动、适配 safe area，并保持在 DSH 抽屉上方。
+
+## 安装
+
+要求：
+
+- 带 Web profile 的 DeepSeek Harness
+- Node.js 20 或更新版本
+- 已验证的 DSH 版本：`0.1.2-rc.1`
+
+已经安装 `dsh` 命令：
+
+```sh
+dsh plugin --profile web add dsh-update-status@latest
+```
+
+直接使用 DeepSeek Harness 源码：
+
+```sh
+corepack enable
+pnpm install
+pnpm dsh plugin --profile web add dsh-update-status@latest
+```
+
+安装后重启原有 DSH 进程，再刷新 Web GUI。不要为本插件启动第二个 Web server。
+
+本地开发 link：
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run build
+dsh plugin --profile web add "link:$(pwd)"
+```
+
+## 使用
+
+1. 打开 DSH 左侧抽屉。官方鱼标仍在；名称行显示 `DeepSeek + 当前版本 Badge`。
+2. 点击 Badge。面板打开时不会触发外层“新建会话”按钮。
+3. 查看有意义的通道。如果 `next` 与当前运行版/稳定版相同，它会被主动隐藏。
+4. 想体验预览版时，在面板中选择 `alpha`。未验证兼容的版本仍会明确警告。
+5. 复制生成的命令，在**运行 DSH 的那台电脑**的终端中自行执行。
+6. 包管理器命令完成后，由你自行重启 DSH。
+
+全局安装时可能生成：
+
+```sh
+npm install -g @deepseek-ai/dsh@latest
+npm install -g @deepseek-ai/dsh@next
+npm install -g @deepseek-ai/dsh@alpha
+```
+
+插件只显示与检测到的安装方式和所选通道匹配的一条命令，不会运行这些命令。
+
+## 发布通道
+
+| 通道 | 用途 | 兼容性处理 |
+| --- | --- | --- |
+| `latest` | DSH npm 包推荐的默认稳定/候选版本 | 只有本插件明确声明过才显示已验证 |
+| `next` | 与当前运行版/稳定版确实不同时的候选版本 | 可能尚未验证 |
+| `alpha` | 用户主动选择的早期预览版 | 除非明确声明，否则显示尚未验证 |
+
+插件严格遵循 npm dist-tag，不会从 registry 历史版本中自行挑选 SemVer 最大值。
+
+## 兼容性
+
+| 插件版本 | 已验证的 DeepSeek Harness |
+| --- | --- |
+| `0.1.0` | `0.1.2-rc.1` |
+
+更高 DSH 版本不会被自动宣称为兼容，需要人工验证。不兼容时请禁用或卸载插件，不要修改 DSH 核心。
+
+## 配置
+
+| 选项 | 默认值 | 范围 / 行为 |
+| --- | --- | --- |
+| `cacheTtlMinutes` | `360` | 30–1,440 分钟；仅在下一次按需读取时判断是否到期，绝不启动后台定时器 |
+| `channel` | `latest` | `latest`、`next` 或 `alpha` |
+| `sidebarEnabled` | `true` | 只隐藏本插件自己的侧栏入口 |
+
+**设置 → 版本与更新** 可隐藏本插件侧栏入口和选择发布通道；详情面板中也能直接切换通道和填写缓存时长。修改缓存时长不会请求网络；只在之后普通读取且缓存已到期时更新，“检查更新”始终是立即手动检查。
+
+## 安全边界
+
+- registry 访问只允许 HTTPS `registry.npmjs.org`，并拒绝重定向。
+- Host 只通过 DSH 已认证的 Connection RPC 返回普通 JSON。
+- 不注册公共 Remote Service，也不注册模型 Tool。
+- 插件代码不会启动 npm/pnpm 子进程。
+- `canApplyInPlace` 恒为 `false`。
+- 没有“立即更新”、自动安装、重启、回滚或 release 文件替换。
+- 刷新失败时保留最后一次成功缓存并显示警告；冷启动失败也会保留本地版本信息。
+
+## 卸载
+
+```sh
+dsh plugin --profile web remove dsh-update-status
+```
+
+重启 DSH 并刷新 Web GUI。如需清除偏好，可在卸载后从 `~/.dsh/settings.yaml` 删除 `dsh-update-status` 命名空间。
+
+## 开发
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run test
+pnpm run build
+pnpm pack --dry-run
+```
+
+发布 tag 使用 npm Trusted Publishing 与 GitHub OIDC。请按 [docs/RELEASING.md](docs/RELEASING.md) 在 npm 网站一次性绑定 Trusted Publisher，随后推送匹配的 `vX.Y.Z` tag；仓库不保存长期 npm token。
+
+MIT，详见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# The host half is a plain static Cordis plugin. package.json's dsh.client
+# declaration loads the built ./client browser half into the current Web GUI.
+- insert:
+    - id: dsh-update-status
+      name: dsh-update-status

package/docs/RELEASING.md

@@ -0,0 +1,114 @@
+# Releasing dsh-update-status
+
+Releases are built from immutable Git tags and published by GitHub Actions. npm packages are immutable: never reuse a version that npm has accepted.
+
+## First release bootstrap
+
+npm cannot authorize Trusted Publishing for a package until that package exists and has an npm-side Trusted Publisher configured. For the initial `0.1.0` bootstrap only, the release workflow uses the repository `NPM_TOKEN` secret through `NODE_AUTH_TOKEN`.
+
+The token must belong to the npm account or organization that owns `dsh-update-status`, have publish permission, and satisfy that account’s 2FA/automation requirements. Never put it in a source file, local `.npmrc`, issue, or workflow log. After `0.1.0` succeeds, configure OIDC as below and remove the Secret before the next version.
+
+## One-time npm Trusted Publisher configuration after first publish
+
+After the first package exists at [npmjs.com](https://www.npmjs.com/), add a **Trusted Publisher**:
+
+| npm field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Owner | `idoall` |
+| Repository | `dsh-update-status` |
+| Workflow filename | `release.yml` |
+| Environment | Leave blank |
+
+The workflow path must be `.github/workflows/release.yml`. After confirming the Trusted Publisher is active, change the publish step back to OIDC (remove `NODE_AUTH_TOKEN`), retain `id-token: write`, remove the repository `NPM_TOKEN` Secret, and test the next release with a new version/tag.
+
+## What a release tag does
+
+Pushing a tag matching `v*` triggers [`.github/workflows/release.yml`](../.github/workflows/release.yml):
+
+1. Require `vX.Y.Z` to exactly match `package.json`’s `X.Y.Z` version.
+2. Install dependencies with a frozen lockfile, run tests, build, and pack exactly one `.tgz` artifact.
+3. Upload that artifact and `SHA256SUMS` as a GitHub Actions artifact.
+4. Publish that same artifact to npm with the bootstrap token and the `latest` dist-tag. After the first successful publish and npm-side configuration, later releases use Trusted Publishing (GitHub OIDC).
+5. Create (or update) the GitHub Release and attach the tarball and checksum **only after** the publish job succeeds.
+
+If `dsh-update-status@X.Y.Z` already exists on npm, the immutable npm package is left unchanged and the workflow continues safely to the GitHub Release step.
+
+## Before every release
+
+Never release an uncommitted worktree or reuse a published npm version.
+
+```sh
+git switch main
+git pull --ff-only
+git status --short
+pnpm install --frozen-lockfile
+pnpm run verify
+node -p "require('./package.json').version"
+```
+
+`git status --short` must be empty, and the printed version must be the intended unpublished version.
+
+For an extra local artifact check:
+
+```sh
+rm -rf .tmp/release && mkdir -p .tmp/release
+pnpm pack --pack-destination .tmp/release
+shasum -a 256 .tmp/release/dsh-update-status-*.tgz
+npm pack --dry-run .tmp/release/dsh-update-status-*.tgz
+```
+
+Before the first release, verify npm does not already own the exact version:
+
+```sh
+VERSION="$(node -p "require('./package.json').version")"
+npm view "dsh-update-status@$VERSION" version || true
+```
+
+## Publish a version
+
+After npm Trusted Publishing is configured and the matching source commit is on `main`:
+
+```sh
+VERSION="$(node -p "require('./package.json').version")"
+git tag -a "v$VERSION" -m "dsh-update-status v$VERSION"
+git push origin "v$VERSION"
+```
+
+Watch the **Release** workflow in GitHub Actions. It publishes npm and creates the GitHub Release; do not run `npm publish` locally for a tag-managed release.
+
+## Verify the public package
+
+After the workflow succeeds:
+
+```sh
+VERSION="$(node -p "require('./package.json').version")"
+npm view "dsh-update-status@$VERSION" name version dist-tags repository --json
+npm view dsh-update-status dist-tags --json
+
+VERIFY_DIR="$(mktemp -d)"
+cd "$VERIFY_DIR"
+npm pack "dsh-update-status@$VERSION"
+npm install --ignore-scripts "./dsh-update-status-$VERSION.tgz"
+node -e "const p=require('./node_modules/dsh-update-status/package.json'); console.log(p.name,p.version,p.dsh?.client?.platform)"
+```
+
+The final command must print:
+
+```text
+dsh-update-status X.Y.Z web
+```
+
+Then install the package in a disposable DSH profile and manually verify the sidebar badge, panel, release-channel selection, cache-duration setting, and mobile drawer behavior:
+
+```sh
+TEST_HOME="$(mktemp -d)"
+DSH_HOME="$TEST_HOME" dsh plugin --profile web add "dsh-update-status@$VERSION"
+DSH_HOME="$TEST_HOME" dsh web
+```
+
+Stop the disposable DSH Web process after verification. The plugin remains advisory: it does not install, restart, roll back, download, or replace DSH files.
+
+## Candidate builds without publication
+
+Use **Actions → Build release candidate → Run workflow** to make a downloadable package and checksum without publishing npm or creating a GitHub Release. This is useful for pre-tag DSH UI verification.