dsh-clean-desktop-shell 0.1.6 → 0.1.8

package/CONTRIBUTORS.md

@@ -0,0 +1,19 @@
+# Contributors
+
+This project welcomes contributions — especially around platforms that the
+maintainer does not use daily.
+
+## Author
+
+- **Icather** — Windows side, plugin architecture, backend lifecycle, CI setup.
+
+## Looking for help
+
+- **macOS maintainer / co-developer**: validate the .dmg install flow,
+  test Apple Silicon + Intel builds, set up code signing + notarization,
+  and ideally add a launch-at-login menu item in the tray.
+- **Linux maintainer**: validate the runtime provisioning and tray behavior
+  on major distributions.
+
+If you open a PR or verified issue that moves macOS support forward, add your
+name here.

package/README.en.md

@@ -11,8 +11,11 @@ Does exactly one thing: wraps your already-configured DSH Web in a clean native
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-0078D6?logo=windows&logoColor=white)](https://github.com/Icather/dsh-clean-desktop-shell)
 [![License](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/Icather/dsh-clean-desktop-shell?color=blue)](https://github.com/Icather/dsh-clean-desktop-shell/releases/latest)
-[![DSH](https://img.shields.io/badge/DeepSeek_Harness-rc.7-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![DSH](https://img.shields.io/badge/DeepSeek_Harness-0.1.1--rc.2-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
 [![Contributors](https://img.shields.io/github/contributors/Icather/dsh-clean-desktop-shell?color=blueviolet)](https://github.com/Icather/dsh-clean-desktop-shell/graphs/contributors)
+[![npm downloads](https://img.shields.io/npm/dt/dsh-clean-desktop-shell?logo=npm&color=cb3837&label=npm%20downloads)](https://www.npmjs.com/package/dsh-clean-desktop-shell)
+[![Installs](https://img.shields.io/github/downloads/Icather/dsh-clean-desktop-shell/total?logo=github&color=2ea043&label=installs)](https://github.com/Icather/dsh-clean-desktop-shell/releases)
+[![Clones](https://img.shields.io/badge/clones-139%20%2F%2014d-8957E5?logo=github&label=clones)](https://github.com/Icather/dsh-clean-desktop-shell)
 
 </div>
 
@@ -27,7 +30,25 @@ Key differences from other desktop clients in the ecosystem:
 | **Form** | Standalone Electron app with its own profile | **DSH plugin** mounted into your existing profile |
 | **Profile** | New `desktop` profile, plugins/config must be reinstalled | **Reuses your web profile**, zero migration |
 | **Visual changes** | Custom title bar / frosted glass etc. | **None** — pure window shell |
-| **Upstream** | Pinned version | **Tracks rc.7** |
+| **Upstream** | Pinned version | **Tracks 0.1.1-rc.2** |
+
+## Highlights
+
+**① One-click launch — like double-clicking a normal desktop app**
+
+No terminal, no commands. **Double-click the desktop shortcut and the DSH window opens instantly**, just like launching any normal app:
+
+- The installer creates the desktop shortcut automatically; the plugin form asks on first run, plus a one-click "create desktop shortcut" in the tray
+- Shows immediately on double-click — never waits for the backend
+- Single instance: a second double-click just focuses the existing window
+
+**② Live backend monitoring · quick manual start/stop**
+
+The tray **shows the backend state in real time** (running / starting / stopped / error) with one-click controls:
+
+- **Live monitoring**: the window keeps probing the backend; the moment it is killed, crashes or is stopped, the window flips to the offline screen — a stale page never fakes "still alive"
+- **Auto-reconnect**: the instant the backend recovers, the window reloads the real page by itself
+- **Quick start/stop**: one-click start / restart / stop from the tray (with progress dialogs); "stop backend" really shuts the service down on 3080, including externally started instances
 
 ## Usage
 
@@ -48,6 +69,61 @@ Key differences from other desktop clients in the ecosystem:
 - The instant the backend stops (tray stop, kill or crash) the window flips back to the offline screen — a stale page never fakes "still alive"
 - The offline screen has self-service buttons: reload / start backend / auto-detect backend / set backend install folder
 
+## macOS status (v0.1.7 important note)
+
+v0.1.7 fixes the plugin-mode bug where the shell could not locate `Electron.app`
+on macOS, which caused the window to fail silently on Mac.
+
+However, **the maintainer does not currently have a Mac** to verify the
+following in person:
+
+- **The .dmg is unsigned and un-notarized**: Apple requires a yearly Developer
+  Program membership ($99/yr) for code signing + notarization. The first time you
+  open the app from the .dmg, Gatekeeper will likely say the app is "damaged"
+  or "cannot be verified".
+  - Workaround: run `xattr -cr "/Applications/DSH Clean Desktop Shell.app"`,
+    then right-click the app and choose Open.
+  - Long-term fix: a Mac co-maintainer with an Apple Developer account can help
+    set up signed + notarized builds.
+- Post-extract executable bits and quarantine extended attributes can only be
+  confirmed on real hardware.
+- **If the window still does not appear**: a failed launch writes diagnostics
+  to `desktop-shell-launch.log` inside your DSH home:
+
+  ```sh
+  cat "${DSH_HOME:-$HOME/.dsh}/desktop-shell-launch.log"
+  ```
+
+  Paste the contents into an issue — it records platform, arch, Node version,
+  DSH home, runtime directory and the exact error. With no window on screen,
+  this is the only thing that can tell us what went wrong.
+
+If you have a Mac and want to co-maintain macOS support (test the .dmg, set up
+signing, or add a launch-at-login tray item), PRs and verified issues are very
+welcome. You will be added to [CONTRIBUTORS.md](./CONTRIBUTORS.md).
+
+## Security & permissions: what it actually does
+
+Third-party scanners (e.g. [dsh-xray](https://github.com/unStone/dsh-xray)) rate
+this project as "high capability combined with sensitive behavior". **That rating
+is not a false positive** — every item is real, and every item has a concrete,
+necessary reason. You should know what runs on your machine.
+
+| Behavior | Why it is required | Where |
+|:--|:--|:--|
+| Spawning system commands | The shell's core job is **starting / restarting / stopping the `dsh web` backend** and probing port 3080. There is no way to do that without system commands. | `electron/service.js` |
+| Downloading the ~100MB Electron runtime | Needed on first launch. Two sources race with a 3s timeout: `github.com` and `npmmirror.com` — the latter is a CN mirror that is usually much faster on Chinese networks. | `src/host/runtime.js` |
+| Calling `api.github.com` | Only for the tray's "Check for updates" action, to read the latest release metadata. | `electron/update.js` |
+| Reading env vars | Path resolution and feature switches only: `DSH_HOME` (DSH home), `DSH_SHELL_ELECTRON_DIR` (reuse a local Electron, skip the download), `DSH_SHELL_AUTO_LAUNCH=0` (disable auto-launch), `USERPROFILE` / `APPDATA` (locate `dsh.cmd` and the shortcuts folder on Windows). | `src/host/common.js`, `src/host/index.js`, `electron/shortcut.js` |
+| Patching the DSH runtime (`cordis.patch.yml`) | **DSH's official plugin registration mechanism** — every DSH plugin mounts this way, it is not specific to this project. | `cordis.patch.yml` |
+
+**The line it does not cross**: no telemetry, no uploads, no reading of your
+conversation data. The network requests above are the only two kinds that exist,
+and both can be avoided entirely by setting `DSH_SHELL_ELECTRON_DIR`.
+
+The unsigned-installer warnings (Windows SmartScreen, macOS Gatekeeper) come from
+the **absence of a code-signing certificate**, not from any of the above.
+
 ## Install
 
 **Option 1: download the installer from Releases (for a standalone desktop app)**
@@ -55,7 +131,13 @@ Key differences from other desktop clients in the ecosystem:
 - Windows: `DSH-Clean-Desktop-Shell-Setup-<version>.exe`
 - macOS: `DSH-Clean-Desktop-Shell-<version>.dmg` (Intel) or `-arm64.dmg` (Apple Silicon)
 
-The installer **creates a desktop shortcut automatically** and provides the full desktop experience (tray). The first time you run the Windows installer you may see a SmartScreen warning — **this is normal for unsigned programs, not a virus**, see "Windows SmartScreen warning" below.
+The installer **creates a desktop shortcut automatically** and provides the full desktop experience (tray).
+
+- **Windows**: the first time you run the installer you may see a SmartScreen
+  warning — **this is normal for unsigned programs, not a virus**, see
+  "Windows SmartScreen warning" below.
+- **macOS**: the .dmg is unsigned / un-notarized and may trigger Gatekeeper.
+  See "macOS status" above.
 
 **Option 2: install as a DSH plugin (DSH ecosystem users)**
 
@@ -149,6 +231,29 @@ npm run pack    # package NSIS (Win) / DMG (mac)
 
 ## Changelog
 
+### 0.1.7
+- **Fixed a silent failure that made the window never open on macOS**: the
+  Electron macOS archive is an `Electron.app` bundle with the binary at
+  `Electron.app/Contents/MacOS/Electron`; the launcher was looking for a
+  top-level `electron` (the Linux layout) and gave up without any feedback.
+- Extraction now tries multiple strategies (ditto / unzip / tar) and verifies
+  the payload; the executable bit is restored and the macOS quarantine
+  attribute is cleared afterwards.
+- Launch failures no longer vanish into the log: diagnostics are written to
+  `desktop-shell-launch.log` and its full path is reported.
+- macOS tray now uses a template image so it adapts to light/dark menu bars;
+  the Windows-only "create desktop shortcut" item is hidden elsewhere.
+- Added `CONTRIBUTORS.md` and an open call for Mac co-maintainers (signing,
+  notarization, real-device verification).
+
+### 0.1.6
+- Fixed "check for updates" reporting the Electron runtime version in plugin mode.
+
+### 0.1.5
+- Refactored the plugin host half into focused modules.
+- Completed package.json metadata (repository / homepage / bugs); dropped a stale auto-launch field.
+- README: usage before install, architecture reflects the two forms, platform matrix top-level.
+
 ### 0.1.4
 - Branch 2 (plugin-market distribution) is now live: `dsh plugin add` →
   restart `dsh web` → the desktop shell opens automatically. The Electron

package/README.md

@@ -11,8 +11,11 @@
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-0078D6?logo=windows&logoColor=white)](https://github.com/Icather/dsh-clean-desktop-shell)
 [![License](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/Icather/dsh-clean-desktop-shell?color=blue)](https://github.com/Icather/dsh-clean-desktop-shell/releases/latest)
-[![DSH](https://img.shields.io/badge/DeepSeek_Harness-rc.7-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![DSH](https://img.shields.io/badge/DeepSeek_Harness-0.1.1--rc.2-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
 [![Contributors](https://img.shields.io/github/contributors/Icather/dsh-clean-desktop-shell?color=blueviolet)](https://github.com/Icather/dsh-clean-desktop-shell/graphs/contributors)
+[![npm downloads](https://img.shields.io/npm/dt/dsh-clean-desktop-shell?logo=npm&color=cb3837&label=npm%20downloads)](https://www.npmjs.com/package/dsh-clean-desktop-shell)
+[![Installs](https://img.shields.io/github/downloads/Icather/dsh-clean-desktop-shell/total?logo=github&color=2ea043&label=installs)](https://github.com/Icather/dsh-clean-desktop-shell/releases)
+[![Clones](https://img.shields.io/badge/clones-139%20%2F%2014d-8957E5?logo=github&label=clones)](https://github.com/Icather/dsh-clean-desktop-shell)
 
 </div>
 
@@ -27,7 +30,25 @@
 | **形态** | 独立 Electron 应用，自带独立 profile | **DSH 插件**，挂载进现有 profile |
 | **Profile** | 新建 desktop profile，插件/配置要重装 | **复用现有 web profile**，零迁移 |
 | **视觉改造** | 自绘标题栏 / 毛玻璃等 | **零改造**，纯净窗口壳 |
-| **跟随上游** | 固定版本 | **跟随 rc.7** |
+| **跟随上游** | 固定版本 | **跟随 0.1.1-rc.2** |
+
+## 核心亮点
+
+**① 像双击桌面应用一样，一键启动 DSH**
+
+不用开终端、不用记命令。**双击桌面快捷方式，DSH 窗口立刻弹出**，和启动任何一个普通软件一样自然：
+
+- 安装包自动创建桌面快捷方式；插件形态首次运行询问 + 托盘「创建桌面快捷方式」一键补建
+- 双击即出窗——窗口不等后端、不做启动等待
+- 单实例：重复双击只聚焦已有窗口，绝不重复开壳
+
+**② 后端活性实时监测 · 快捷手动自主启停**
+
+托盘**实时显示后端状态**（运行中 / 启动中 / 未运行 / 错误），一键启停：
+
+- **活性监测**：窗口持续探测后端；后端一旦被杀、崩溃或手动关闭，窗口立刻切到离线页，绝不停在旧页面假装还活着
+- **自动重连**：后端恢复的一刻，窗口自动加载回真实页面，无需手动刷新
+- **快捷启停**：托盘右键一键启动 / 重启 / 关闭后端（带进度弹窗）；「关闭后端」真正停掉 3080 端口上的服务，含外部启动的实例
 
 ## 使用
 
@@ -48,6 +69,42 @@
 - 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
 - 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
 
+## macOS 状态（v0.1.7 重要说明）
+
+v0.1.7 修复了插件形态在 macOS 上无法定位 `Electron.app` 路径的问题（该 bug 导致窗口在 Mac 上完全静默失败）。
+
+但**当前开发者没有 Mac 实机**，以下事项仍然依赖 Mac 用户验证/贡献：
+
+- **.dmg 安装包未签名、未公证**：Apple 要求年度开发者计划（$99/年）才能给安装包签名+公证。首次打开 .dmg 里的应用，很可能提示「已损坏，无法打开」或「无法验证开发者」。这不是应用本身损坏，是 Gatekeeper 拦截了未签名应用。
+  - 临时解决：`xattr -cr "/Applications/DSH Clean Desktop Shell.app"`，然后右键 → 打开。
+  - 长期解决：需要一位有 Apple Developer 账号的 Mac 合作者协助签名/公证，或长期把 .dmg 安装体验写为「需要右键打开 / 执行 xattr」。
+- **Electron.app 解压后的可执行位、quarantine 扩展属性等**只有真机能确认行为是否完全正确。
+- **如果窗口还是没弹出来**：启动失败时会把诊断信息写到 DSH home 下的 `desktop-shell-launch.log`：
+
+  ```sh
+  cat "${DSH_HOME:-$HOME/.dsh}/desktop-shell-launch.log"
+  ```
+
+  把内容贴到 Issue 即可——里面记录了平台、架构、Node 版本、DSH home、运行时目录和具体报错。没有界面时，这是唯一能回传的信息。
+
+诚挚邀请有 Mac 环境、愿意一起打磨的同学参与：能帮忙验证安装流程、补充签名配置、或者把开机自启/登录项做进 Electron 托盘，欢迎直接提 PR 或在 Issue 里 @ 我，我会把你加入 [CONTRIBUTORS.md](./CONTRIBUTORS.md)。
+
+## 安全与权限：它到底做了什么
+
+第三方安全扫描器（如 [dsh-xray](https://github.com/unStone/dsh-xray)）会给本项目打出「高能力 + 敏感行为」的评级。这个评级**没有误报**——列出的每一条都属实，但每一条都有明确且必要的原因。既然要装进你的机器，就该摊开讲清楚。
+
+| 行为 | 为什么必须这么做 | 代码位置 |
+|:--|:--|:--|
+| 执行系统命令（spawn） | 壳的核心功能就是**启动 / 重启 / 停止 `dsh web` 后端**，以及探测 3080 端口占用。不调用系统命令无法实现。 | `electron/service.js` |
+| 下载约 100MB 的 Electron 运行时 | 首次启动需要。两个源按网络环境自动竞速（3 秒超时）：`github.com` 与 `npmmirror.com`——后者是国内镜像，CN 网络下通常更快。 | `src/host/runtime.js` |
+| 访问 `api.github.com` | 仅用于托盘「检查更新」拉取最新 Release 信息。 | `electron/update.js` |
+| 读取环境变量 | 只用于定位路径和功能开关：`DSH_HOME`（DSH 主目录）、`DSH_SHELL_ELECTRON_DIR`（复用本地 Electron，跳过下载）、`DSH_SHELL_AUTO_LAUNCH=0`（关闭自动弹窗）、`USERPROFILE` / `APPDATA`（Windows 下定位 `dsh.cmd` 与快捷方式目录）。 | `src/host/common.js`、`src/host/index.js`、`electron/shortcut.js` |
+| 修改 DSH 运行时（`cordis.patch.yml`） | **DSH 官方的插件注册机制**，所有 DSH 插件都靠它挂载，并非本项目特有行为。 | `cordis.patch.yml` |
+
+**边界**：不上传任何数据、不读取会话内容、不回传遥测。全部网络请求只有上面两类（下载运行时 / 查更新），且都可通过设置 `DSH_SHELL_ELECTRON_DIR` 完全避免。
+
+安装包的未签名警告（Windows SmartScreen、macOS Gatekeeper）来自**缺少代码签名证书**，与上述行为无关。
+
 ## 安装
 
 **方式一：从 Release 下载安装包（想要独立桌面应用的用户）**
@@ -55,7 +112,12 @@
 - Windows：下载 `DSH-Clean-Desktop-Shell-Setup-<版本>.exe`
 - macOS：下载 `DSH-Clean-Desktop-Shell-<版本>.dmg`（Intel）或 `-arm64.dmg`（Apple Silicon）
 
-安装包会**自动创建桌面快捷方式**，并提供系统托盘等完整桌面体验。首次运行 Windows 安装包可能触发 SmartScreen 警告——**这是未签名程序的正常现象，不是病毒**，见下方「Windows SmartScreen 警告说明」。
+安装包会**自动创建桌面快捷方式**，并提供系统托盘等完整桌面体验。
+
+- **Windows**：首次运行安装包可能触发 SmartScreen 警告——**这是未签名程序的正常现象，不是病毒**，见下方「Windows SmartScreen 警告说明」。
+- **macOS**：.dmg 未签名/未公证，首次打开可能触发 Gatekeeper。见上方「macOS 状态」。
+
+
 
 **方式二：作为 DSH 插件安装（DSH 生态用户）**
 
@@ -150,6 +212,21 @@ npm run pack    # 打包 NSIS (Win) / DMG (mac)
 
 ## 更新历史
 
+### 0.1.7
+- **修复 macOS 上窗口完全打不开的静默失败**：Electron 的 macOS 包是 `Electron.app` 应用包，可执行文件位于 `Electron.app/Contents/MacOS/Electron`；此前按 Linux 布局去找顶层 `electron`，导致 Mac 上必然启动失败且无任何提示。
+- 解压改为多策略回退（ditto / unzip / tar）并校验产物；解压后补齐可执行位，清除 macOS quarantine 扩展属性。
+- 启动失败不再只写日志：诊断信息落盘到 `desktop-shell-launch.log`，并在提示中给出完整路径。
+- macOS 托盘改用模板图，深浅色菜单栏自适应；非 Windows 平台隐藏「创建桌面快捷方式」。
+- 新增 `CONTRIBUTORS.md`，公开招募 Mac 合作开发者（代码签名 / 公证 / 实机验证）。
+
+### 0.1.6
+- 修复插件形态下「检查更新」误报 Electron 运行时版本号的问题。
+
+### 0.1.5
+- 插件 host 侧重构为聚焦模块。
+- 补全 package.json 元数据（repository / homepage / bugs），清理遗留的开机自启字段。
+- README 调整：使用前置、架构反映两种形态、平台矩阵置顶。
+
 ### 0.1.4
 - 分支二（插件市场分发）正式可用：`dsh plugin add` 装插件 → 重启 `dsh web` → 桌面壳自动弹出；Electron 运行时由插件自管理（本地复用 / 按网络环境自动选源下载）。
 - 桌面快捷方式：首次启动询问创建 + 托盘「创建桌面快捷方式」一键添加（安装包与插件两种形态均支持）。

package/electron/tray.js

@@ -25,8 +25,12 @@ import { shortcutSupported, createDesktopShortcut } from './shortcut.js'
 const trayIconPath = join(
   fileURLToPath(new URL('.', import.meta.url)),
   'assets',
-  process.platform === 'win32' ? 'tray-16.png' : 'tray-32.png',
+  process.platform === 'win32' ? 'tray-16.png' : 'trayTemplate.png',
 )
+// macOS: the filename must end in "Template" (e.g. trayTemplate.png) and
+// Electron will automatically pick trayTemplate@2x.png on Retina.
+// The image itself must be a black silhouette + alpha channel so it
+// inverts correctly in both light and dark menu bars.
 
 let trayInstance = null
 let handlers = null
@@ -61,9 +65,11 @@ export function refreshTrayMenu() {
       label: '刷新窗口',
       click: onReload,
     },
+    // Windows-only: desktop .lnk shortcut. Hidden on other platforms instead of
+    // disabled so the menu stays relevant to the OS it is running on.
     {
       label: '创建桌面快捷方式',
-      enabled: shortcutSupported(),
+      visible: shortcutSupported(),
       click: async () => {
         const ok = await createDesktopShortcut()
         if (ok) {

package/electron/update.js

@@ -18,6 +18,8 @@ import { loadConfig } from './config.js'
 
 const REPO_URL = 'https://github.com/Icather/dsh-clean-desktop-shell'
 const RELEASES_API = 'https://api.github.com/repos/Icather/dsh-clean-desktop-shell/releases/latest'
+// npm registry — the update source for plugin (npm-installed) mode.
+const NPM_REGISTRY_API = 'https://registry.npmjs.org/dsh-clean-desktop-shell'
 
 // Plugin (bare-runtime) mode has no app bundle, so app.getVersion() returns
 // the Electron runtime version (e.g. 33.4.11). Read the plugin's own version
@@ -125,9 +127,10 @@ export async function checkForUpdatesAuto() {
     return
   }
 
-  // Manual path (macOS / dev mode): compare versions, offer GitHub page.
-  const r = await checkForUpdate()
+  // Manual path. Plugin mode is installed via npm/DSH market, so it checks the
+  // npm registry; the packaged desktop app checks GitHub Releases.
   const isPlugin = !app.isPackaged
+  const r = isPlugin ? await checkForUpdateNpm() : await checkForUpdate()
   if (r.hasUpdate) {
     const choice = dialog.showMessageBoxSync({
       type: 'info',
@@ -145,13 +148,15 @@ export async function checkForUpdatesAuto() {
     dialog.showMessageBoxSync({
       type: 'info',
       title: '已是最新版本',
-      message: `当前版本 ${r.current} 已是最新（${r.latest}）。`,
+      message: `当前版本 ${r.current} 已是最新。`,
     })
   } else {
     dialog.showMessageBoxSync({
       type: 'warning',
       title: '检查更新失败',
-      message: '无法连接 GitHub 检查更新，请检查网络后重试。',
+      message: isPlugin
+        ? '无法连接 npm 检查更新，请检查网络后重试。'
+        : '无法连接 GitHub 检查更新，请检查网络后重试。',
     })
   }
 }
@@ -227,3 +232,37 @@ export function openRepo() {
 export function openUrl(url) {
   shell.openExternal(url)
 }
+
+/**
+ * Version check for plugin (npm-installed) mode. The plugin is updated through
+ * the npm registry / DSH market, so its "latest" must come from npm — NOT from
+ * GitHub Releases (that endpoint is only for the packaged desktop app).
+ * @returns {{ hasUpdate: boolean, latest?: string, current: string, url: string }}
+ */
+export async function checkForUpdateNpm() {
+  const current = currentVersion()
+  let latestStr = null
+  const url = 'https://www.npmjs.com/package/dsh-clean-desktop-shell'
+
+  try {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), 8000)
+    const res = await fetch(NPM_REGISTRY_API, { signal: controller.signal })
+    clearTimeout(timer)
+    if (res.ok) {
+      const data = await res.json()
+      latestStr = data['dist-tags']?.latest || null
+    }
+  } catch {
+    // Network error — no update known.
+  }
+
+  const currentV = parseVersion(current)
+  const latestV = parseVersion(latestStr)
+  return {
+    hasUpdate: isNewer(latestV, currentV),
+    latest: latestStr ? `v${latestStr}` : null,
+    current,
+    url,
+  }
+}

package/lib/common.js

@@ -12,11 +12,42 @@ import { fileURLToPath } from 'node:url'
 export const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 export const MAIN_JS = join(PKG_ROOT, 'electron', 'main.js')
 export const isWin = process.platform === 'win32'
-export const EXE_NAME = isWin ? 'electron.exe' : 'electron'
+export const isMac = process.platform === 'darwin'
 export const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
-export const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
+export const PLATFORM = isWin ? 'win32' : isMac ? 'darwin' : 'linux'
+
+/**
+ * Electron binary path *relative to the extracted runtime dir*.
+ *
+ * The three upstream archives do not share a layout — only darwin ships an
+ * app bundle, and it is the one case with no top-level executable:
+ *   win32  → electron.exe
+ *   linux  → electron
+ *   darwin → Electron.app/Contents/MacOS/Electron
+ *
+ * Authoritative source: the `electron` package's own install.js, which writes
+ * exactly this relative path into path.txt for `require('electron')`.
+ */
+export const EXE_RELPATH = isWin
+  ? 'electron.exe'
+  : isMac
+    ? join('Electron.app', 'Contents', 'MacOS', 'Electron')
+    : 'electron'
+
+/** First path segment of EXE_RELPATH — what a successful extract must leave behind. */
+export const EXE_TOP = isWin ? 'electron.exe' : isMac ? 'Electron.app' : 'electron'
+
+/** DSH home, honouring DSH_HOME the same way dsh-home-paths does. */
+export function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh')
+}
 
 /** Where the self-provisioned runtimes live (shared with icon.js). */
 export function runtimeRoot() {
-  return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'desktop-shell-runtime')
+  return join(dshHome(), 'desktop-shell-runtime')
+}
+
+/** Launch diagnostics land here — the only thing a headless user can send us. */
+export function launchLogPath() {
+  return join(dshHome(), 'desktop-shell-launch.log')
 }

package/lib/index.js

@@ -9,7 +9,8 @@
  * icon.js (Windows taskbar icon).
  */
 import { spawn } from 'node:child_process'
-import { PKG_ROOT, MAIN_JS } from './common.js'
+import { appendFileSync } from 'node:fs'
+import { PKG_ROOT, MAIN_JS, dshHome, runtimeRoot, launchLogPath } from './common.js'
 import { ensureRuntime } from './runtime.js'
 import { patchExeIcon } from './icon.js'
 
@@ -36,11 +37,50 @@ export function apply(ctx) {
       await patchExeIcon(ctx, exe).catch(() => {})
       launchShell(exe, ctx)
     } catch (err) {
-      ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
+      reportLaunchFailure(ctx, err)
     }
   })()
 }
 
+/**
+ * A provisioning failure used to vanish into ctx.logger — invisible to
+ * anyone who is not already tailing the DSH log. That is precisely how the
+ * macOS launch bug survived several releases: there was no window, no error
+ * dialog, and nothing on disk to send back.
+ *
+ * Write a diagnostics file next to the runtime and name it in the warning,
+ * so a user on an untested platform can hand us something actionable.
+ */
+function reportLaunchFailure(ctx, err) {
+  const message = err?.message ?? String(err)
+  ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${message}`)
+
+  const logPath = launchLogPath()
+  const body = [
+    `time:     ${new Date().toISOString()}`,
+    `platform: ${process.platform} (${process.arch})`,
+    `node:     ${process.version}`,
+    `dsh home: ${dshHome()}`,
+    `runtime:  ${runtimeRoot()}`,
+    `entry:    ${MAIN_JS}`,
+    `error:    ${message}`,
+    '',
+    'Things worth checking:',
+    '  - first launch downloads the Electron runtime; a blocked network fails here',
+    '  - set DSH_SHELL_ELECTRON_DIR to an electron package to skip the download',
+    '  - macOS binary: <runtime>/electron-v<ver>/Electron.app/Contents/MacOS/Electron',
+    '  - macOS: unsandboxed extractors may drop the executable bit (chmod +x)',
+    '',
+  ].join('\n')
+
+  try {
+    appendFileSync(logPath, body + '\n')
+    ctx.logger.warn(`[clean-desktop-shell] diagnostics written to ${logPath}`)
+  } catch {
+    // Nothing else a headless host process can do.
+  }
+}
+
 function launchShell(exe, ctx) {
   if (launched) return
   const child = spawn(exe, [MAIN_JS], {