@zhengjunyao/dsh-restart 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+本文件记录 `@zhengjunyao/dsh-restart` 的所有可见变更。版本纪律：破坏性变更不得走 patch（0.x 走 minor、1.x+ 走 major）。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-12
+
+首个版本。
+
+### Added
+
+- **一键重启**：设置页「重启」卡片 + 左侧边栏入口（与其它插件入口并排）+ 全屏重启遮罩；点一下即把重启交给分离的重启助手。
+- **两种重启策略，自动识别**：
+  - launchd 托管（本机默认场景）→ 助手执行 `launchctl kickstart -k`，让 launchd 自己拉起，助手退居观察者并跟随 plist 日志；
+  - 非托管 → 助手用**完全相同的 argv/cwd/env** 重新拉起，等端口真正释放而不是赌固定延时。
+- **自动重连**：页面探测 `/api/dsh-restart/probe`，新宿主一应答就自动刷新载入新代码；状态写 `sessionStorage`，重启中途刷新页面也能续跑（`autoReload` 可关）。
+- **失败可读**：新进程 stdout/stderr 实时进日志，疑似报错行被单独挑出显示；DSH 已完全挂掉时，助手自带的恢复控制台（默认 `http://127.0.0.1:3099`，CORS 开放）仍可用（阶段/日志/报错行/退出码 + 一键重试）。
+- **失败报告**：失败时写一份自包含单文件 `~/.dsh/dsh-restart/last-failure.md`，控制台 `GET /report` 与页面「复制完整报告」一键取用。
+- **agent 工具**：`dsh_restart_status`（只读）、`dsh_restart`（需 `confirm: true`，重启前必须先获得用户同意）。
+- 配置 `~/.dsh/dsh-restart.json`（0600）；日志 `~/.dsh/dsh-restart/logs/`；重启历史 `history.json`。
+
+### Notes
+
+- 插件目录按 DSH 约定解析：`DSH_RESTART_HOME` → `DSH_HOME` → `~/.dsh`。
+- 同机多实例共享插件目录时，助手状态按 `oldPid`/`childPid` 判归属，不会把兄弟实例的失败算到本机头上。
+- 已知限制：UI 目前为中文单语；headless / cron profile 因 `inject` 要求 `webServer` 而不会加载。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhengjy01
+
+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,116 @@
+# @zhengjunyao/dsh-restart
+
+English | [中文](README.zh.md)
+
+A restart button for DeepSeek Harness. Installing or updating a plugin changes
+host-side code, and only a fresh `dsh web` process picks it up — that used to
+mean going back to a terminal. Now it is one click in the Web GUI: the page
+reconnects on its own, and **if the new process fails to boot, the error is
+shown right there** (an in-page overlay, plus a recovery console on its own port
+that stays up even when DSH is dead).
+
+## Why
+
+A self-restart is the moment things go wrong invisibly: the tab loses its
+server, the new process crashes, and the only trace is in a terminal you already
+left. `dsh-restart` handles all three:
+
+- **one click** from the settings card or the sidebar entry;
+- **two strategies, auto-detected** — when the host is a launchd job
+  (`com.dsh.web`, `KeepAlive`), the helper delegates with
+  `launchctl kickstart -k` and only *observes* (spawning our own host would race
+  the job for the port); otherwise it relaunches the exact same command
+  (argv / cwd / env / Node flags) after waiting for the port to be *actually*
+  released, instead of guessing with a fixed delay;
+- **the new process's stdout+stderr stream into a log**, the lines that look like
+  errors are lifted out, and the helper's recovery console
+  (`http://127.0.0.1:3099` by default, CORS-open) keeps answering after DSH is
+  gone — showing phase, boot log, error lines and exit code, with a one-click
+  retry.
+
+## Features
+
+- Settings card 「重启」, sidebar entry next to your other plugin entries, and a
+  full-screen overlay while the handoff happens.
+- Auto-reconnect: the page probes `/api/dsh-restart/probe` and reloads itself as
+  soon as the new host answers (`autoReload`, on by default).
+- Failure handling: error lines are detected (Error / EADDRINUSE /
+  MODULE_NOT_FOUND / stack frames), the boot log is shown in the overlay, and
+  `maxAttempts` (default 2) automatic retries run before giving up.
+- Agent tools: `dsh_restart_status` (read-only) and `dsh_restart`, which demands
+  `confirm: true` because the local standing rule is that DSH is never restarted
+  without explicit user consent.
+- History at `~/.dsh/dsh-restart/history.json`; logs under
+  `~/.dsh/dsh-restart/logs/`; config at `~/.dsh/dsh-restart.json` (0600).
+
+## Install
+
+```sh
+dsh plugin --profile web add @zhengjunyao/dsh-restart   # npm
+dsh plugin --profile web add link:/path/to/dsh-restart
+# or, from GitHub (repo tagged with the dsh-plugin topic)
+dsh plugin --profile web add github:zhengjy01/dsh-restart
+```
+
+Restart `dsh web` once to load it — the last manual restart you need.
+
+## HTTP surface
+
+All loopback-only, same-origin, matching the other `dsh-*` panels:
+`GET /status`, `GET /probe`, `POST /restart`, `GET /logs`, `GET /history`,
+`POST /config`, `GET /helper`, `POST /helper/retry` — all under
+`/api/dsh-restart/`.
+
+## How it works
+
+```
+panel / dsh_restart
+      │ POST /api/dsh-restart/restart
+      ▼
+  host (old process) ──writes pending-spec.json──▶ detached helper (zero deps)
+      │ replies 202, SIGTERMs itself ~0.7s later              │
+      ▼                                                       │ waits for the port
+   process exits ─────────────────────────────────────────────┤
+                                                              ▼
+                                     spawns the new host with the same command
+                                     (stdout/stderr → logs/<stamp>-<pid>.log)
+                                                              │
+                     status.json ◀── phase/progress/errors ───┤
+                     http://127.0.0.1:3099 ◀── recovery console┘
+                                                              │
+   page polls /probe ──▶ new host answers ──▶ location.reload()┘
+```
+
+## Compatibility
+
+- **Requires** DeepSeek Harness **≥ 0.1.5-rc.1** (declared as `dsh.engines.dsh`).
+- **Verified against**: **0.1.5-rc.1** on macOS with Node 25.8.1 — host half, browser half and a real restart.
+- **Platforms**: only **macOS** has actually been exercised. When the host is launchd-managed, the helper delegates with `launchctl kickstart -k`; elsewhere it falls back to relaunching the same command itself (the launchd path is platform-guarded; Linux and Windows are untested).
+- Compatibility is also derived from the union of the `@deepseek-ai/dsh-*` `peerDependencies` ranges, which is what the plugin market displays.
+
+## Tests
+
+```sh
+pnpm test    # 129 assertions across five suites
+```
+
+`smoke` (config/history/log detection/host identity), `helper` (the real helper
+against fake hosts: crash capture + console + manual retry, and a successful
+relaunch), `routes` (synthetic req/res, including the loopback/cross-site/method
+guards), `handoff` (end-to-end on fake ports: restart → old process really exits
+→ helper relaunches generation 2 → the port answers with a new pid), `launchd`
+(pid→job matching and observe mode, which must never spawn).
+
+## Limits
+
+- Only restarts: it does not install plugins or repair a profile (that is
+  `dsh-doctor`'s job).
+- A restart always interrupts the current turn and connection — replacing the
+  host process cannot be invisible. What is guaranteed is that the interruption
+  is *observable, recoverable, and its errors readable*.
+- The helper registers no OS-level service; it lives for one restart and exits
+  after readiness (or stays put on failure until you deal with it).
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,163 @@
+# @zhengjunyao/dsh-restart
+
+[English](README.md) | 中文
+
+给 DeepSeek Harness 装一个「重启」按钮：装完/更新插件后不用再回终端敲命令，
+在 Web GUI 里点一下就把 DSH 重启了——页面自己重连、自己刷新；**如果新进程起不来，
+它会把报错直接显示出来**（页内遮罩 + 一个独立端口的恢复控制台）。
+
+## 为什么需要它
+
+宿主侧的插件代码（`lib/index.js`、bundle 清单、`dsh.client` 清单）只有换一个
+`dsh web` 进程才会生效，所以每次装插件都得手动重启一次。而这个「手动重启」本身
+是最容易出事的环节：
+
+- 重启后进程起不来 → 浏览器一片空白，看不到任何原因；
+- 新进程崩溃/端口占用 → 只有终端能看见报错；
+- 重启期间页面直接失联 → 只能靠人手刷新。
+
+`dsh-restart` 把这三件事都接住了。
+
+## 能力
+
+- **一键重启**：设置页「重启」卡片、左侧边栏「重启」入口（与其它插件入口并排），
+  点一下即完成交接。
+- **两种重启策略，自动识别**：
+  - **launchd 托管（本机默认）**：宿主是 launchd 任务（`com.dsh.web`、`KeepAlive`）时，
+    自己 spawn 一个宿主会和 launchd 抢端口，所以改为助手 `launchctl kickstart -k` 让
+    launchd 自己重启，助手退居**观察者**（只等端口回来 + 跟随 plist 的 stdout/stderr 日志），
+    绝不重复拉起。
+  - **自拉起**：非托管宿主则由助手用**完全相同的 argv/cwd/env** 重新拉起，
+    先等端口真正释放（不是赌固定延时）再 spawn，不会撞 `EADDRINUSE`。
+  - 助手本身是 detached 的零依赖纯 Node ESM（`helper/restart-helper.mjs`），
+    两种策略共用同一套日志/状态/控制台。
+- **自动重连**：页面按配置的间隔探测 `/api/dsh-restart/probe`，新宿主一应答就自动
+  刷新（`autoReload`，默认开），载入新代码。
+- **报错直显**：新进程的 stdout+stderr 实时流入 `~/.dsh/dsh-restart/logs/*.log`；
+  助手把疑似报错的行（Error / EADDRINUSE / MODULE_NOT_FOUND / 调用栈 …）单独挑出来，
+  在页内遮罩里显示；DSH 已经完全挂掉时，助手自己的恢复控制台
+  （默认 `http://127.0.0.1:3099`，CORS 开放）仍然可用，能看到阶段、启动日志、
+  报错行、退出码，并可一键「重试启动」。
+- **失败自动重试**：`maxAttempts`（默认 2）次内自动重试；都失败就停在那里等人工处理，
+  不会把端口/日志丢掉。
+- **Agent 工具**：`dsh_restart_status`（只读：宿主 pid/端口/版本/启动时长/启动命令、
+  助手阶段与失败原因、最近重启记录、上次启动日志里的疑似报错行）、
+  `dsh_restart`（真正重启；**必须已获得用户同意**并传 `confirm: true`，
+  否则只返回提示不执行）。
+- **重启历史**：`~/.dsh/dsh-restart/history.json` 记录每次重启的时间、来源、原因、
+  新旧 pid 与日志路径。
+
+## 安装
+
+```sh
+# 本地开发
+dsh plugin --profile web add @zhengjunyao/dsh-restart   # npm
+dsh plugin --profile web add link:/path/to/dsh-restart
+# 从 GitHub（仓库打 dsh-plugin topic）
+dsh plugin --profile web add github:zhengjy01/dsh-restart
+```
+
+装完需要重启一次 `dsh web` 才会加载——**这一次是最后一次手动重启**。
+
+## 使用
+
+1. 打开「设置 → 插件配置 → Web 插件 → 重启」（或点左侧边栏的重启图标）。
+2. 点「立即重启」：
+   - 出现重启遮罩，显示阶段（下发指令 → 旧进程退出 → 新宿主启动 → 已就绪）与已等待时间；
+   - 宿主退出（launchd 托管时由 `launchctl kickstart -k` 触发）、助手接管、新宿主起来后页面自动刷新；
+   - 若新宿主起不来，遮罩里直接出现 `Error: …` 与日志尾部，可「复制报错」「让助手重试启动」
+     「打开恢复控制台」。
+3. 面板里还能看到：宿主信息、上次启动日志（含疑似报错行）、重启记录、插件设置。
+
+## 配置
+
+`~/.dsh/dsh-restart.json`（0600，首次加载时按插件行种子生成；面板可改）：
+
+| 键 | 默认 | 含义 |
+| --- | --- | --- |
+| `enabled` | `true` | 总开关（关闭后不挂载路由与工具） |
+| `announceToAgent` | `true` | 在系统提示里公告插件能力 |
+| `entry` | `sidebar` | 入口位置：`sidebar` / `ball` / `both` / `off` |
+| `restartMode` | `auto` | `auto`（识别到 launchd 就交给它）/ `launchd`（强制，找不到任务则报错）/ `helper`（强制自拉起） |
+| `fallbackPort` | `3099` | 恢复控制台端口（被占用时自动 +1…+9） |
+| `bootTimeoutMs` | `120000` | 新宿主多久没应答算这次尝试失败 |
+| `maxAttempts` | `2` | 单次重启请求的启动尝试次数 |
+| `killGraceMs` | `6000` | 端口迟迟不释放时，助手 SIGKILL 旧进程前的宽限 |
+| `portFreeTimeoutMs` | `25000` | 等旧进程释放端口的上限 |
+| `lingerMs` | `4000` | 就绪后助手退出前保留控制台的时间 |
+| `logLines` | `200` | 面板/接口返回的日志行数 |
+| `autoReload` | `true` | 新宿主应答后自动刷新页面 |
+| `showOverlay` | `true` | 重启时显示全屏遮罩 |
+| `probeIntervalMs` | `1200` | 重连探测间隔 |
+| `historyLimit` | `30` | 重启历史保留条数 |
+
+## HTTP 接口
+
+全部 loopback-only（127.0.0.1 / ::1，同源），沿用其它 dsh-* 面板的守卫：
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/api/dsh-restart/status` | 宿主 + 助手 + 配置 + 历史 |
+| GET | `/api/dsh-restart/probe` | 极小存活探针（重连时高频轮询） |
+| POST | `/api/dsh-restart/restart` | 交接重启，先回 202 再退出本进程 |
+| GET | `/api/dsh-restart/logs` | 启动日志尾部 + 疑似报错行 |
+| GET | `/api/dsh-restart/history` | 重启记录 |
+| POST | `/api/dsh-restart/config` | 改配置 / `reset: true` 恢复默认 |
+| GET | `/api/dsh-restart/helper` | 经宿主读取助手实时状态 |
+| POST | `/api/dsh-restart/helper/retry` | 让失败的助手再试一次 |
+
+## 工作方式
+
+```
+面板 / dsh_restart
+      │ POST /api/dsh-restart/restart
+      ▼
+  宿主（旧进程）──写 pending-spec.json──▶ 分离的助手进程（detached，零依赖）
+      │ 回 202，延迟 ~0.7s 后 SIGTERM 自己                    │
+      ▼                                                      │ 等端口释放
+   进程退出 ─────────────────────────────────────────────────┤
+                                                             ▼
+                                        用完全相同的命令 spawn 新宿主
+                                        （stdout/stderr → logs/<时间>-<pid>.log）
+                                                             │
+                     status.json ◀── 阶段/进度/报错 ──────────┤
+                     http://127.0.0.1:3099 ◀── 恢复控制台 ───┘
+                                                             │
+   页面轮询 /probe ──▶ 新宿主应答 ──▶ location.reload() ◀─────┘
+```
+
+## 兼容性
+
+- **要求**：DeepSeek Harness **≥ 0.1.5-rc.1**（即 `package.json` 的 `dsh.engines.dsh`）。
+- **实测通过**：**0.1.5-rc.1**（macOS + Node 25.8.1；宿主半、客户端半、真实重启全流程）。
+- **平台**：只在 **macOS** 上实测过。macOS 且宿主由 launchd 托管时走 `launchctl kickstart -k`；其它平台自动落到「分离助手自拉起」路径（代码里对 launchd 有平台守卫，Linux / Windows 未实测）。
+- 兼容性判定也来自 `peerDependencies` 的 `@deepseek-ai/dsh-*` 范围并集（插件市场展示的是这一项）。
+
+## 测试
+
+```sh
+pnpm test        # 129 项断言，五个套件
+```
+
+- `tests/smoke.mjs` — 配置读写与钳制、历史、日志尾部与报错识别、启动签名、宿主信息；
+- `tests/helper.mjs` — **真的**跑助手：崩溃路径（捕获退出码、stderr 报错行、控制台页面、
+  手动重试）与成功路径（等端口 → 拉起 → 就绪计时）；
+- `tests/routes.mjs` — 合成的 req/res 打全部路由，含 loopback/跨站/方法守卫；
+- `tests/handoff.mjs` — 端到端：假宿主进程 → POST 重启 → 旧进程真的退出 →
+  助手用相同命令拉起第二代 → 端口重新应答（新 pid）、`restarted: true`、历史落盘；
+- `tests/launchd.mjs` — launchd 识别（**按 pid 匹配 `launchctl list`**，因为 Node 会把
+  `XPC_SERVICE_NAME` 改写成 `0`）+ observe 模式（助手执行 kickCommand、跟随托管方日志、
+  **绝不自己 spawn**）。
+
+## 边界
+
+- 只负责「重启」这一件事：不做插件安装、不做配置修复（那是 `dsh-doctor` 的领域）。
+- 重启一定会中断当前回合与连接——这是宿主进程被替换的必然结果；本插件保证的是
+  **中断可见、可恢复、报错可读**，而不是「不中断」。
+- 助手不会注册任何 OS 级后台服务；它就活一次重启，成功后就绪 + 保留控制台数秒即退出，
+  失败时留在原地等你处理（可随时 `kill`）。
+- `dsh_restart` 工具强制 `confirm: true`：本机规则是未经用户同意不得重启 DSH。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-restart bundle patch: inserts the plugin row into the profile roster.
+# Applied as a profile bundle layer (declared by the `dsh.bundle.patch`
+# manifest field in package.json). Activate with:
+#
+#   # local development (link)
+#   dsh plugin --profile web add @zhengjunyao/dsh-restart
+#   # after publishing to GitHub (repo tagged with the `dsh-plugin` topic)
+#   dsh plugin --profile web add github:zhengjy01/dsh-restart
+- insert:
+    - id: restart
+      name: '@zhengjunyao/dsh-restart'
+      config:
+        announceToAgent: true   # 在系统提示中公告插件（工具 + 能力说明）
+        enabled: true           # 插件总开关
+        # 其余设置只是「首次写入 ~/.dsh/dsh-restart.json 的种子」；真正的
+        # 开关在配置文件里（面板「插件设置」或直接改文件），重启助手每次
+        # 重启都会重新读取。