dsh-shutdown-guard 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v1.5.1 — 2026-11-04
+
+- 三语界面：中文 / English / Русский。宿主侧文案目录 78 键、侧边栏卡片 74 键，三语键集齐平、零缺失；日志与提示全部改走 `t(lang, key)`，`lib/index.mjs` 内已无硬编码中文串。
+- 新增语言选择器：设置 → 插件 → 任务完成后关机 → 「语言」，切换即时生效——经 `POST /api/dsh-shutdown-guard/config` 的 `language` 字段落盘，卡片强制重绘，不需要重启 DSH。
+- 新增 `language` 配置项：取值 `auto` | `zh` | `en` | `ru`，默认 `auto`（跟随系统语言）。它由 `loadStore`（`lib/index.mjs:283`）读取、经 `POST /config` 在运行时写入；**不是** `normalizeProfile` 字段，三份 README 的配置表已单独为它补一行。
+- 语言偏好同时写入宿主配置（`data/config.json`）与浏览器 `localStorage`：前者是权威值，后者让卡片在首帧就按所选语言渲染，重启后不再闪一下中文。
+- 文档：新增 `README.en.md`、`README.ru.md`，三份 README 的配置表统一补 `language` 行；演示页改成三语（`scripts/demo/i18n.js`，157 键）。
+- 修复：切换语言后，事件日志里切换前的旧行会永久停留在旧语言；现在切换时整环重取（`lib/client.js` `setSnapshot`）。
+- 修复：`saveStore()` 在 `apply()` 外引用越界变量，写 `data/config.json` 失败时会抛 `ReferenceError`、`log.configWriteFailed` 提示永远打不出来（`lib/index.mjs:292-295`、`:1039`）。
+- 可访问性：设置里 5 个开关补 `aria-label`，屏幕阅读器可读出开关名称（未新增文案键）。
+- 测试：新增 i18n 目录断言——`LANGS` 固定为三语、`catalogCoverage().missing` 为空、每语键数与基准一致。
+- ⚠️ 升级注意：**已有配置无需任何改动或迁移**。`language` 缺省即 `auto`，与 v1.5.0 的行为一致；升级后若想固定语言，在设置里选一次即可。
+
 ## v1.5.0 — 2026-11-02
 
 - 改名：`dsh-shutdown-panel` → **`dsh-shutdown-guard`**（Shutdown Guard）。原名只描述了界面，没表达它真正的特长——关机前逐条排除。`shutdown` 仍在包名第二位，市场按关键词搜索时排序不受影响。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ltayshark0637
-
-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
+MIT License
+
+Copyright (c) 2026 ltayshark0637
+
+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.en.md

@@ -0,0 +1,263 @@
+# Shutdown Guard · Shut down when tasks finish
+[中文](README.md) · **English** · [Русский](README.ru.md)
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/banner.png" width="880" alt="Shutdown Guard — automatic shutdown when tasks finish, a night-watch card in the sidebar"></p>
+
+[![version](https://img.shields.io/badge/version-1.5.1-2ea44f)](CHANGELOG.md)
+[![demo](https://img.shields.io/badge/%E2%96%B6-LIVE%20DEMO-d97757)](https://ltayshark0637.github.io/dsh-Shutdown-Guard/demo.html)
+[![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.1.5--rc.1-4a90d9)](https://github.com/deepseek-ai)
+[![platform](https://img.shields.io/badge/platform-Windows-0078d4)](#constraints)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Adds a "shut down automatically when all tasks finish" card to the DeepSeek Harness sidebar, with a more varied and polished visual treatment, decision logic, and customization. It sits below Skill Center and above the session list, and updates in real time with task state.
+
+**▶ [Interactive demo](https://ltayshark0637.github.io/dsh-Shutdown-Guard/demo.html)** — no installation needed; see what it looks like and how it decides. Two panes: **Learn** (rules, appearance, states) and **Try** (a random scenario where you arm the guard, cancel it, and release it yourself, all the way to a shutdown or a block). All data is generated locally at random; nothing is sent over the network.
+
+## Why you need it
+
+People who run long tasks know this scene: you hand the agent a batch of work in the evening, want the machine to shut down when it is done, and you are not at the desk.
+
+But "task finished" does not mean "safe to shut down" — background jobs may still be running, a session may have errored, the agent may be waiting for your answer, or you may have stopped it halfway. Shutting down in any of those cases is an incident. The plugin blocks each of these situations and shuts down only when it is genuinely safe.
+
+## Rules: when it actually shuts down
+
+In a blocked state (see below) nothing is sent at all; otherwise all five gates must pass before `shutdown /s` is issued:
+
+1. **Armed** — you turned it on manually
+2. **No countdown already running** — avoids duplicate issuance
+3. **All root sessions idle** — no agent is still working
+4. **No running or stopping background jobs** — `blockOnJobs`, on by default
+5. **No session error in this batch** — `onlyOnSuccess`, on by default
+
+If any one is missing, it does not shut down and writes the reason on the card and in the settings page.
+
+## Three looks
+
+| A · Hazard tape                                                             | B · Radar                                                        | C · Terminal                                                                             |
+|:----------------------------------------------------------------------:|:---------------------------------------------------------------:|:------------------------------------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/02-armed.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/06-variant-b-radar.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/07-variant-c-terminal.png" width="250"> |
+| Large status text + scrolling red-and-yellow stripes at the bottom                                          | Concentric rings + a scanning beam, sessions and background jobs shown as dots                      | Command-line summary + six indicator lights for the gate conditions                                                      |
+
+Dots in the radar are added and removed, never reordered: when the count changes, the dots you are looking at do not jump.
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/anim-radar.gif" width="330" alt="Radar sweep"></p>
+
+Switch in settings; takes effect immediately, no restart needed.
+
+## Six runtime states
+
+| Off                                              | Standby                                                  | Waiting on background jobs                                                           |
+|:---------------------------------------------------:|:-----------------------------------------------------:|:----------------------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/01-off.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/02-armed.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/03-hold.png" width="250"> |
+
+| Countdown                                               | Issued                                                                  | Blocked                                                                     |
+|:----------------------------------------------------:|:-----------------------------------------------------------------------:|:------------------------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/04-fire.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/05-fired.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/08-blocked-halted.png" width="250"> |
+
+`Off` → `Standby` → `Waiting on background jobs` → `Countdown` → `Issued`; a blocking error at any stage moves it to `Blocked`. You can cancel at any point during the countdown; **cancelling leaves it armed** — the next batch will still shut down.
+
+Want to flip through all six states? In section 04 of the demo's Learn pane, the three capsules `A` `B` `C` at the top right switch which look the preview uses.
+
+## Blocked states
+
+| halted · needs manual action                                            | waiting · retries automatically                                                                |
+|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/08-blocked-halted.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/09-blocked-waiting.png" width="250"> |
+
+For errors that cannot be handled as ordinary failures, the plugin **stays armed**, changes the card's colour, and writes out the reason:
+
+- **`halted`** (slate blue) — insufficient quota, invalid credentials, context overrun, unsupported capability, disk full. Only a human can resolve it; click "disarm and retry".
+- **`waiting`** (slate green, a breathing dot) — rate limiting, 5xx, network interruption, empty response, timeout, image offload. Retried automatically according to policy; at the right moment a "continue the original plan" instruction is injected.
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/anim-blocked.gif" width="380" alt="Waiting for recovery, the status dot breathing"></p>
+
+Retry cadence is configured per failure type; see [Retry policies](#retry-policies).
+
+## AFK auto-pilot
+
+When nobody is at the desk, the plugin covers three things for you:
+
+- **Auto-answer questions** (on by default): when the agent asks something, it replies "The user is AFK. Finish the tasks already assigned, write up a summary report to disk, and do not touch branches that were not assigned." It returns `selected: []` plus custom text, so **it never selects an option for you**; turn this off and questions come to you as usual.
+- **Error recovery**: when a session errors, the agent is first asked to investigate and continue the original plan; a second failure in the same session switches to "stop retrying and write up a report".
+- **Interruption protection**: if you stop a task yourself midway, that does not trigger a shutdown.
+
+## Where it lives
+
+| Armed: below Skill Center, above the session list                                                          | Countdown: same spot, the whole strip turns red                                                              |
+|:-------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/10-sidebar-hold.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/11-sidebar-fire.png" width="250"> |
+
+The card is currently pinned to this sidebar slot. A future version plans to make it available as a standalone widget (with a switch in settings); this section will be updated then.
+
+## Other details
+
+- **Vertical collapse**: collapsed it keeps only the title and status; click the title to expand.
+
+  <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/16-folded.png" width="250" align="right" alt="Collapsed state">
+
+- **Theme adaptation**: the card carries its own `--dsp-*` palette and picks light or dark automatically from the host surface's brightness; you can also force dark / light / Claude Style.
+
+- **Event log**: the settings page shows recent events and "why it did not shut down last time"; the full stream is in `data/events.log`.
+
+<br clear="all">
+
+## Settings page
+
+| Dark                                                                                          | Light                                                                                           |
+|:---------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/12-settings-dark.png" width="380"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/13-settings-light.png" width="380"> |
+
+Three groups: Appearance / When to shut down / Status. Every switch takes effect immediately.
+
+- **Default profile** is locked at 60 seconds and cannot be changed; there are 8 custom slots you can tune freely.
+- "All sessions idle" is the floor condition, always on and not switchable.
+- "Background jobs finished" blocks background jobs; "skip this round if any session errored" blocks erroring batches.
+- "AFK auto-answer" controls whether questions are answered for you while armed; the description states "replies never select an option for you; turn this off and questions come to you as usual."
+
+## Light and third-party themes
+
+| Light card                                              | Claude Style                                           |
+|:-----------------------------------------------------:|:------------------------------------------------------:|
+| <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/14-light.png" width="250"> | <img src="https://cdn.jsdelivr.net/gh/ltayshark0637/dsh-Shutdown-Guard@main/docs/screenshots/15-claude.png" width="250"> |
+
+The card does not inherit the host palette; it brings its own, while the settings page follows the host theme. The third-party Claude Style theme has a matching palette too.
+
+## Installation
+
+Published on npm; recommended:
+
+```bash
+dsh plugin --profile web add dsh-shutdown-guard
+```
+
+Or install straight from GitHub:
+
+```bash
+dsh plugin --profile web add github:ltayshark0637/dsh-Shutdown-Guard
+```
+
+Then **restart DSH**.
+
+> ⚠️ **The client bundle is only wired into the module graph at DSH startup**: after editing `lib/client.js` you must restart; refreshing the page does nothing. The same applies to the server side.
+
+**On a restricted network**: the GitHub command is essentially `pnpm add github:...` and needs a clone. If cloning fails, prefer the npm command (it goes through the registry); if neither works, install from a local path — DSH Settings → Plugins → Add, enter the **absolute path** of this directory → Install → restart.
+
+**Manual fallback**: create a symlink `node_modules\dsh-shutdown-guard` under `profiles\web` pointing at this directory, then:
+
+- add `link:<absolute path of this directory>` to `dependencies` and `pnpm.overrides` in `profiles\web\package.json`
+- append `dsh-shutdown-guard` to `dsh.profile.bundles`
+
+## Permissions and impact
+
+Once installed, the plugin does the following:
+
+| Area | Concrete behaviour |
+| --- | --- |
+| **Command execution** | Calls Windows `shutdown.exe` through `subprocess`: `/s /t <seconds>` schedules the shutdown, `/a` cancels it. **Only invoked when armed and all five gates pass** |
+| **File access** | Only `data/` inside the plugin directory: `config.json` (configuration) and `events.log` (event log) |
+| **Events** | `agent/status`, `agent/error`, `session/event`, `user-questions/request` |
+| **HTTP routes** | Under the local DSH Web server, `/api/dsh-shutdown-guard/`: `GET /state`, `GET /events`, `POST /arm`, `POST /disarm`, `POST /cancel`, `POST /config`; POST validates that Origin is `127.0.0.1` or `localhost` |
+| **Network** | **No external requests at all**, no data collection |
+| **Platform** | **Windows only**. On anything other than `win32` the plugin silently does not load |
+
+While AFK auto-pilot is on, the plugin answers the agent's questions and injects recovery instructions into erroring sessions during armed periods; you can switch this off at any time in settings.
+
+## Configuration
+
+Written in `cordis.patch.yml` (the patch inside the plugin package), or changed at runtime via `POST /config`.
+
+| Key              | Range   | Default   | Description                                      |
+| --------------- | ------ | ------ | ----------------------------------------- |
+| `countdownSec`  | 10–600 | 60     | Seconds of countdown before shutdown (fixed at 60 in the default profile, not editable) |
+| `marginSec`     | 0–60   | 5      | Extra margin passed to `shutdown /t`             |
+| `onlyOnSuccess` | bool   | `true` | Skip the shutdown when any session in this batch errored |
+| `blockOnJobs`   | bool   | `true` | Skip the shutdown while background jobs are running |
+| `afkAutoAnswer` | bool   | `true` | Answer questions and perform error recovery for the user while armed |
+| `language`      | enum   | `auto` | UI language; `auto` follows the system language, or pin it to `zh` / `en` / `ru` |
+
+### Retry policies
+
+Each error code is assigned a policy name; the policies themselves are configurable:
+
+| Policy         | Default cadence                               | Assigned to                             |
+| ------------ | -------------------------------------- | ---------------------------------- |
+| `rate-limit` | backoff 30 → 60 → 120 → 240 → 300, capped | `RATE_LIMIT`                       |
+| `transient`  | fixed 20 seconds                             | `SERVER` / `TRANSPORT` / `TIMEOUT` |
+| `empty`      | fixed 30 seconds                             | `EMPTY_RESPONSE`                   |
+| `offload`    | fixed 5 seconds                              | `IMAGE_OFFLOAD_REQUIRED`           |
+
+Rate limiting uses backoff rather than a fixed interval because hammering a rate-limited service **extends** the limit rather than just wasting requests. 5xx and network failures recover on a predictable timescale, so a fixed interval is simply faster. Image offload is a local disk operation and is almost immediately retryable, hence 5 seconds.
+
+Override a single error code:
+
+```yaml
+retryAssign:
+  RATE_LIMIT: slow-limit
+retryPolicies:
+  slow-limit: { mode: backoff, base: 60, max: 900 }
+```
+
+An unknown `code` falls back to `transient`; malformed policies are dropped and the defaults are kept. The currently effective assignments are available from `retryAssign` and `retryPolicies` in `/state`.
+
+UI preferences live in the browser's `localStorage`: `dsh-shutdown-guard.variant` / `.theme` / `.folded`.
+
+## HTTP API
+
+Prefix `/api/dsh-shutdown-guard`, used by the card's own same-origin polling:
+
+| Method | Path                       | Description                                                                             |
+| ---- | -------------------------- | -------------------------------------------------------------------------------- |
+| GET  | `/state?since=<ms>`        | Full state plus incremental events                                                              |
+| POST | `/arm` `/disarm` `/cancel` | Arm / disarm / cancel this countdown                                                     |
+| POST | `/config`                  | Change configuration: `customEnabled`, `activeProfileId`, `profileId`+`patch`, `afkAutoAnswer`, `language` |
+| GET  | `/events?since=&limit=`    | Event stream                                                                         |
+
+POSTs from a non-local Origin return 403; non-POST returns 405.
+
+## Logs
+
+- `<plugin directory>\data\events.log` — human-readable event stream (categories `config` / `afk` / `skip`); the settings page's "Event log" reads it
+- `<DSH_HOME>\dsh-shutdown-guard.log` — process-level append log
+
+## Development
+
+```bash
+node test/host.test.mjs        # server: 26 assertions, mock ctx, never actually shuts down
+node test/client.test.cjs      # client bundle smoke test
+node scripts/gen-gallery.cjs   # generate the screenshot page from the real CSS in lib/client.js
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/screenshot.ps1    # headless Edge renders PNGs (transparent background + auto crop)
+node scripts/gen-gif.cjs       # generate the three animated GIFs used in the README
+node scripts/gen-banner.cjs    # generate the 1280x640 social preview image
+node scripts/gen-demo.cjs      # generate docs/demo.html (the interactive demo)
+```
+
+All screenshots are generated from the real CSS in `lib/client.js`, so they cannot drift from the product. The animations work the same way: CSS animations are frozen at several points in time via `animation-delay`, captured frame by frame, and assembled with a built-in GIF89a encoder — no ffmpeg or ImageMagick needed on the machine.
+
+The Learn section of the demo page is rendered live too: the six states are generated on the spot with the same `card()` markup as the product, not captured as screenshots.
+
+## FAQ
+
+**Q: Why does changing a setting do nothing?**
+A: Both the server and the client need DSH restarted to load new code. Local HMR does not apply to locally linked plugins.
+
+**Q: Why didn't it shut down after arming?**
+A: Check "why it did not shut down last time" in settings; it names the specific reason (background jobs, errors, not armed, etc.).
+
+**Q: Can I change my mind during the countdown?**
+A: Yes. Use "Cancel shutdown" on the card or just run `shutdown /a`; cancelling keeps it armed, so the next batch still applies.
+
+**Q: Can it shut down by mistake?**
+A: With the default configuration, the plugin acts only when all four hold — all sessions idle, no background jobs, no errors, and you armed it manually. Breaking any one of them cancels or skips the shutdown. Manual task termination is also detected and excluded.
+
+**Q: Does it work outside Windows?**
+A: Not yet; that is planned for later.
+
+## Constraints
+
+- Windows only: exits early on anything other than `win32` and mounts nothing.
+- Zero runtime dependencies: the server uses only `node:fs` / `node:path` / `node:crypto`, the browser only `require('react')`.
+- Does not modify `app.asar` or DSH source.
+
+## License
+
+[MIT](LICENSE)