@shawnxiaoyang/dsh-tray-restart 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shawn
+
+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

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @shawnxiaoyang/dsh-tray-restart
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让桌面端托盘的「重启 DeepSeek Harness」项在每次自动升级后自动回来。
+
+> **它会修改官方安装包。** 本插件会在你退出应用后，把 `resources/app.asar` 换成一份
+> 打过补丁的副本（原档备份为 `app.asar.heal.bak`）。这属于修改已安装程序，可能触发杀软
+> 告警；如果上游开启了归档完整性校验，插件会拒绝动手（见下文「安全闸门」）。
+
+## 它解决什么问题
+
+桌面端（`DeepSeek Harness.exe`）的托盘右键菜单写在 Electron 主进程里，也就是打包进
+`resources/app.asar` 的 `lib/main.js`。nightly 更新是**整包替换**：升级后 `app.asar`
+被换回官方原版，托盘菜单里就只剩「打开」「退出」。
+
+托盘菜单属于主进程，插件体系碰不到它（主进程的 Tray、没有 restart 类 IPC、渲染进程
+发来的消息还要过 `dsh-app:` 协议校验）。所以本插件不试图"添加菜单项"，而是**修好那个
+装着菜单项的归档文件**——在 Windows 唯一允许替换它的时刻：应用退出之后。
+
+## 安装
+
+```bash
+dsh plugin --profile desktop add @shawnxiaoyang/dsh-tray-restart
+```
+
+装好后重启一次应用即可。**只在 Windows 桌面端生效**：macOS / Linux 的桌面端、以及终端里
+`dsh web` 起的 CLI 形态都没有这套托盘，插件会报告自己空闲并什么都不做。
+
+## 工作方式
+
+1. **发现**：宿主进程是 Electron 主进程的直接子进程，`process.execPath` 和
+   `process.resourcesPath` 就是应用自己的。读 `resources/app.asar` 里的 `lib/main.js`
+   就能判断补丁还在不在。
+2. **暂存**：一个子进程在原归档旁边重建出打过补丁的 `app.asar.heal.new`。它**从不碰**
+   `app.asar`；任何一处锚点对不上就整体放弃，不产出半成品。
+3. **换包**：一个分离的守护进程等 Electron 主进程退出，再核对归档仍是当初构建补丁的那
+   一份（哈希不符说明升级换过了，直接丢弃暂存包，绝不覆盖新版本），然后才把暂存包写进去。
+   写完校验，失败就从备份还原。
+
+`/restart` 补上运行中的一环：暂存 → 布防 → 由守护进程停掉应用并重新拉起。
+
+CLI 形态的 Harness（终端里 `dsh web`）没有 Electron 外壳，插件会报告自己空闲并什么都不做。
+
+## 安全闸门
+
+补丁改的是官方归档，所以有两道闸门在写之前就拦住：
+
+1. **归档完整性校验**（Electron fuse `EnableEmbeddedAsarIntegrityValidation`）。开启时
+   Electron 会拿头部记录逐条校验打包条目，重建的归档必然对不上签名版本，结果是**应用
+   退回默认 Electron 窗口、整个用不了**。插件因此先读可执行文件里的 fuse 位：只要不是
+   明确关闭，就一律拒绝写入（读不到也算不安全）。当前桌面端 0.2.2-rc.3 是关闭的。
+2. **锚点唯一性**。每处改动都要求目标文本在 `lib/main.js` 里恰好出现一次；官方改写结构
+   后会报 `anchor-failed` 并指出是哪一处，不会产出坏包。
+
+设置页会把这两件事的状态直接显示出来。
+
+## 使用
+
+正常使用时不需要做任何事：升级后第一次启动，插件在 4 秒后重建暂存包，等你下次正常退出
+应用时静默换包，再下次启动托盘项就回来了。
+
+想立刻生效，在会话里输入：
+
+```
+/restart
+```
+
+它会重启应用，并顺带把托盘「重启」项修回来。
+
+## 设置页
+
+插件管理里这一行的设置页是只读的，显示：补丁是否在位、桌面端版本、`lib/main.js` 字节数、
+暂存包是否备好、重建用的运行时、归档完整性校验是否开启，以及最近 40 行日志。它通过宿主
+的只读回环路由 `/__tray-restart/status` 取数（非回环、跨站、DNS rebinding 一律 403），
+页面本身没有任何写入路径。
+
+## 配置
+
+| 键 | 默认 | 含义 |
+| --- | --- | --- |
+| `enabled` | `true` | 启用本插件 |
+| `autoHeal` | `true` | 启动时若发现补丁丢失，就在后台重建并暂存 |
+| `restartCommand` | `true` | 注册 `/restart` 命令 |
+
+## 状态与日志
+
+- 日志：`%LOCALAPPDATA%\dsh-tray-restart\heal.log`
+- 暂存包：`<resources>\app.asar.heal.new`
+- 换包备份：`<resources>\app.asar.heal.bak`
+- 守护进程锁：`<resources>\app.asar.heal.lock`
+
+## 边界与已知代价
+
+- 补丁依赖 `lib/main.js` 里的若干锚点文本。新版桌面端改写了这些位置时，插件会报告
+  `anchor-failed` 并给出是哪一处，而不是产出一个坏包。把那条消息发出来即可适配。
+- 换包发生在应用退出之后，因此**升级后的第一次退出**才会真正生效，不是升级瞬间。
+- 换包用"覆盖写"而不是"改名"：Windows 会拒绝给仍被映射的大文件改名，但允许覆盖写。
+  代价是归档有一瞬间是半写状态，因此备份先写好并校验，失败就回滚。
+- 暂存包约 200 MB，构建耗时 1–2 秒，退出时会占一点磁盘 IO。
+- 需要系统里有一个 Node.js 来跑重建子进程（找不到时回退到应用自带的 Electron node 模式）。
+
+## 卸载
+
+从 profile 里移除本插件后，`resources/app.asar` 会保持最后一次换包后的样子（仍是打过
+补丁的归档）。想恢复官方原版，用 `app.asar.heal.bak` 覆盖回去，或者重装一次桌面端。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# @shawnxiaoyang/dsh-tray-restart bundle patch: one host row over the Desktop profile.
+# The row name resolves from the profile's own node_modules where
+# `dsh plugin --profile <profile> add <path>` installed this package.
+- insert:
+    - id: tray-restart
+      name: '@shawnxiaoyang/dsh-tray-restart'

package/lib/asar.mjs

@@ -0,0 +1,262 @@
+/**
+ * Minimal, read-and-rewrite ASAR support for the tray-restart patch.
+ *
+ * Only what this plugin needs: parse the two pickle headers, resolve one entry,
+ * and rebuild the archive after `lib/main.js` changes. The rebuild strategy is
+ * the one the shipped archives tolerate — the patched module is appended after
+ * the original data region (4-byte aligned), its entry offset/size/integrity are
+ * updated, and the header JSON is re-emitted with space padding so the data
+ * region keeps starting on a 4-byte boundary. Every other entry keeps its exact
+ * offset, so its bytes and hash are untouched.
+ *
+ * The header layout, verified against the real 0.2.2-rc.3 archive:
+ *
+ *   [u32 4][u32 headerSize]                      size pickle, 8 bytes
+ *   [u32 payloadLength][u32 jsonLength][json]    header pickle, headerSize bytes
+ *   <data region>                                entries, offsets relative to it
+ *
+ * with `payloadLength === headerSize - 4` and `dataStart === align4(16 + jsonLength)`.
+ *
+ * @module dsh-tray-restart/asar
+ */
+
+import { createHash } from 'node:crypto'
+import { closeSync, fstatSync, openSync, readFileSync, readSync } from 'node:fs'
+
+/** Round up to the next multiple of four. */
+export const align4 = (n) => n + ((4 - (n % 4)) % 4)
+
+/**
+ * Run `fn` with Electron's asar shim disabled.
+ *
+ * Inside the Host process, `resources/app.asar` is treated as a directory, so a
+ * plain `readFileSync` on the archive itself fails with ENOENT. The shim is a
+ * process-wide switch, hence the save/restore: other plugins keep loading their
+ * own modules from the archive while this plugin reads it.
+ *
+ * @param fn - synchronous work that must see real file bytes.
+ * @returns whatever `fn` returned.
+ */
+export function withNoAsar(fn) {
+  const previous = process.noAsar
+  process.noAsar = true
+  try {
+    return fn()
+  } finally {
+    process.noAsar = previous
+  }
+}
+
+/**
+ * Parse and validate the header of an archive on disk, reading only the header.
+ *
+ * @param file - absolute archive path.
+ * @returns header JSON plus the geometry needed to resolve entries.
+ */
+export function readArchiveHeader(file) {
+  const fd = openSync(file, 'r')
+  try {
+    const size = fstatSync(fd).size
+    const head = Buffer.alloc(16)
+    if (readSync(fd, head, 0, 16, 0) < 16) throw new Error('asar: file is shorter than its header')
+    const pickle = head.readUInt32LE(0)
+    if (pickle !== 4) throw new Error(`asar: unexpected size pickle ${pickle}`)
+    const headerSize = head.readUInt32LE(4)
+    const payloadLength = head.readUInt32LE(8)
+    const jsonLength = head.readUInt32LE(12)
+    if (payloadLength !== headerSize - 4) {
+      throw new Error(`asar: header pickle payload ${payloadLength} does not fill ${headerSize - 4}`)
+    }
+    if (jsonLength + 4 > payloadLength) throw new Error(`asar: json ${jsonLength} overflows payload ${payloadLength}`)
+    const dataStart = 8 + headerSize
+    if (dataStart !== align4(16 + jsonLength)) {
+      throw new Error(`asar: unexpected header layout (${dataStart} vs ${align4(16 + jsonLength)})`)
+    }
+    const json = Buffer.alloc(jsonLength)
+    if (readSync(fd, json, 0, jsonLength, 16) < jsonLength) throw new Error('asar: header json is truncated')
+    return { header: JSON.parse(json.toString('utf8')), dataStart, bytes: size, headerSize, jsonLength }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * Parse an archive already in memory.
+ *
+ * @param buffer - complete archive bytes.
+ * @returns the same shape as {@link readArchiveHeader}, plus the buffer.
+ */
+export function readArchiveBuffer(buffer) {
+  const headerSize = buffer.readUInt32LE(4)
+  const payloadLength = buffer.readUInt32LE(8)
+  const jsonLength = buffer.readUInt32LE(12)
+  if (payloadLength !== headerSize - 4) {
+    throw new Error(`asar: header pickle payload ${payloadLength} does not fill ${headerSize - 4}`)
+  }
+  if (jsonLength + 4 > payloadLength) throw new Error(`asar: json ${jsonLength} overflows payload ${payloadLength}`)
+  const dataStart = 8 + headerSize
+  if (dataStart !== align4(16 + jsonLength)) {
+    throw new Error(`asar: unexpected header layout (${dataStart} vs ${align4(16 + jsonLength)})`)
+  }
+  const header = JSON.parse(buffer.subarray(16, 16 + jsonLength).toString('utf8'))
+  return { buffer, header, dataStart, bytes: buffer.length, headerSize, jsonLength }
+}
+
+/** Read the complete archive bytes. Callers wrap this in {@link withNoAsar}. */
+export function readArchiveFull(file) {
+  return readArchiveBuffer(readFileSync(file))
+}
+
+/**
+ * Resolve one entry node by slash-separated path.
+ *
+ * @param header - parsed header JSON.
+ * @param path - entry path such as `lib/main.js`.
+ * @returns the entry node.
+ */
+export function entryOf(header, path) {
+  let node = header
+  for (const segment of path.split('/').filter(Boolean)) {
+    node = node.files?.[segment]
+    if (node === undefined || node === null) throw new Error(`asar: missing entry ${path}`)
+  }
+  return node
+}
+
+/**
+ * Read one entry's bytes from an archive on disk.
+ *
+ * @param file - archive path.
+ * @param archive - result of {@link readArchiveHeader}.
+ * @param path - entry path.
+ * @returns the entry bytes.
+ */
+export function readEntryBytes(file, archive, path) {
+  const entry = entryOf(archive.header, path)
+  const start = archive.dataStart + Number(entry.offset)
+  const size = Number(entry.size)
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(size) || start + size > archive.bytes) {
+    throw new Error(`asar: entry ${path} lies outside the archive`)
+  }
+  const fd = openSync(file, 'r')
+  try {
+    const buffer = Buffer.alloc(size)
+    if (readSync(fd, buffer, 0, size, start) < size) throw new Error(`asar: entry ${path} is truncated`)
+    return buffer
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * Read one entry's bytes from an archive already in memory.
+ *
+ * @param archive - result of {@link readArchiveBuffer}.
+ * @param path - entry path.
+ * @returns the entry bytes.
+ */
+export function readEntryFromBuffer(archive, path) {
+  const entry = entryOf(archive.header, path)
+  const start = archive.dataStart + Number(entry.offset)
+  const size = Number(entry.size)
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(size) || start + size > archive.bytes) {
+    throw new Error(`asar: entry ${path} lies outside the archive`)
+  }
+  return archive.buffer.subarray(start, start + size)
+}
+
+/**
+ * Produce a new archive whose only difference is `lib/main.js`.
+ *
+ * @param source - result of {@link readArchiveFull}.
+ * @param patchedMain - replacement module bytes.
+ * @returns the complete new archive.
+ */
+export function patchArchiveBuffer(source, patchedMain) {
+  const header = structuredClone(source.header)
+  const originalDataLength = source.buffer.length - source.dataStart
+  const alignedOffset = align4(originalDataLength)
+
+  const mainEntry = entryOf(header, 'lib/main.js')
+  mainEntry.offset = String(alignedOffset)
+  mainEntry.size = patchedMain.length
+  mainEntry.integrity = {
+    algorithm: 'SHA256',
+    hash: sha256(patchedMain),
+    blockSize: mainEntry.integrity?.blockSize ?? 4194304,
+    blocks: [sha256(patchedMain)],
+  }
+
+  let json = Buffer.from(JSON.stringify(header), 'utf8')
+  const newJsonLength = align4(json.length + 8) - 8
+  json = Buffer.concat([json, Buffer.alloc(newJsonLength - json.length, 0x20)])
+  const newHeaderSize = newJsonLength + 8
+
+  const head = Buffer.alloc(16)
+  head.writeUInt32LE(4, 0)
+  head.writeUInt32LE(newHeaderSize, 4)
+  head.writeUInt32LE(newJsonLength + 4, 8)
+  head.writeUInt32LE(newJsonLength, 12)
+
+  const padding = Buffer.alloc(alignedOffset - originalDataLength)
+  return Buffer.concat([head, json, source.buffer.subarray(source.dataStart), padding, patchedMain])
+}
+
+/**
+ * Verify a produced archive against its source without trusting the writer.
+ *
+ * Checks the header geometry, that the unchanged data region is byte-identical,
+ * that `lib/main.js` is exactly the patched module with a matching integrity
+ * hash, and that every entry stays inside the file.
+ *
+ * @param output - produced archive bytes.
+ * @param source - source archive (result of {@link readArchiveFull}).
+ * @param patchedMain - expected module bytes.
+ * @returns a short report of what was checked.
+ */
+export function verifyArchiveBuffer(output, source, patchedMain) {
+  const archive = readArchiveBuffer(output)
+  const originalDataLength = source.buffer.length - source.dataStart
+
+  const prefix = output.subarray(archive.dataStart, archive.dataStart + originalDataLength)
+  const originalPrefix = source.buffer.subarray(source.dataStart)
+  if (!prefix.equals(originalPrefix)) throw new Error('verify: the unchanged data region differs from the source')
+
+  const main = readEntryFromBuffer(archive, 'lib/main.js')
+  if (!main.equals(patchedMain)) throw new Error('verify: lib/main.js bytes differ from the patched module')
+  const mainEntry = entryOf(archive.header, 'lib/main.js')
+  if (mainEntry.integrity?.hash !== sha256(main)) throw new Error('verify: lib/main.js integrity hash mismatch')
+
+  for (const path of ['package.json', 'lib/preload-app.cjs', 'renderer/welcome.html', 'dsh/package.json']) {
+    const before = readEntryFromBuffer(source, path)
+    const after = readEntryFromBuffer(archive, path)
+    if (!before.equals(after)) throw new Error(`verify: ${path} bytes changed`)
+  }
+
+  let checked = 0
+  const walk = (node) => {
+    if (Array.isArray(node.files) === true) {
+      for (const child of node.files) walk(child)
+      return
+    }
+    if (node.files !== undefined && node.files !== null) {
+      for (const child of Object.values(node.files)) walk(child)
+      return
+    }
+    if (node.unpacked === true) return
+    const start = archive.dataStart + Number(node.offset)
+    const size = Number(node.size)
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(size) || start + size > archive.bytes) {
+      throw new Error(`verify: entry at ${start} (+${size}) lies outside the archive`)
+    }
+    checked += 1
+  }
+  walk(archive.header)
+
+  return { archiveBytes: output.length, entries: checked, mainBytes: patchedMain.length, mainSha256: sha256(main) }
+}
+
+/** Hex SHA-256 of a buffer. */
+export function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex')
+}