dsh-clean-desktop-shell 0.1.4 → 0.1.6

package/README.en.md

@@ -29,6 +29,25 @@ Key differences from other desktop clients in the ecosystem:
 | **Visual changes** | Custom title bar / frosted glass etc. | **None** — pure window shell |
 | **Upstream** | Pinned version | **Tracks rc.7** |
 
+## Usage
+
+1. If the plugin is installed, launching `dsh` from the command line pops up the desktop window automatically; you can also double-click the desktop shortcut created by the plugin — on par with a native desktop app.
+2. Everything from the original web UI works as-is.
+3. Detailed settings live in the tray right-click menu. The main window adds no controls of its own, keeping the page clean.
+
+**All backend controls live in the tray** — the main window stays a pure shell:
+
+- Start / restart / stop the backend (with progress dialogs; stopping really shuts down the service on 3080, including externally started instances)
+- Auto-detect backend · set the backend install folder (auto-detect default)
+- Reload window · create desktop shortcut · check for updates · repo homepage
+
+**Window reliability (Edge-style instant refresh):**
+
+- Shows immediately on launch, never waits for the backend
+- While the backend is down, a local "backend offline" screen is shown and re-probed; the real page loads automatically the moment it answers
+- 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
+
 ## Install
 
 **Option 1: download the installer from Releases (for a standalone desktop app)**
@@ -87,22 +106,30 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 ## Architecture
 
 ```
-        ┌─────────────────── Core (dsh web / headless service) ───────────────────┐
-        │  Sessions · Agent · Plugins · Memory live here, decoupled from UI       │
-        └─────────────────────────────────────────────────────────────────────────┘
-                              ▲
-              ┌───────────────┴───────────────┐
-              │   dsh-clean-desktop-shell      │
-              │   Electron shell (client)      │
-              │   tray · single-instance ·     │
-              │                              │
-              └────────────────────────────────┘
+        ┌────────────── Core (dsh web / headless service) ──────────────┐
+        │    Sessions · Agent · Plugins · Memory live here,            │
+        │    decoupled from the UI                                     │
+        └───────────────────────────┬───────────────────────────────────┘
+                                    │  http://127.0.0.1:3080 (or remote)
+                                    ▼
+        ┌───────────────────────────────────────────────────────────┐
+        │            dsh-clean-desktop-shell (Electron shell)       │
+        │      tray · single-instance · offline auto-reconnect      │
+        │      · desktop shortcut                                    │
+        │                                                           │
+        │    One shell codebase, two distribution forms:            │
+        │     ├─ Installer: standalone exe, auto-update             │
+        │     └─ Plugin: auto-pops on dsh web start                 │
+        │        (self-managed Electron runtime)                     │
+        └───────────────────────────────────────────────────────────┘
 ```
 
+- **Shell / core separation**: the shell handles only the window, tray and backend management; sessions, agents, plugins and memory all live in the core, decoupled from the UI.
 - **Default**: loads the local `127.0.0.1:3080` (your configured web profile, zero migration).
 - **Remote-capable**: configure any remote DSH address; the shell is just a window. Phones / Linux / other devices can reach the core via browser or PWA — the shell is never bound to a local service.
+- **One shell codebase, two distribution forms**: the installer (standalone exe) and the plugin (launches with `dsh web`) share the same `electron/` code — only the runtime source and launch differ (see Install).
 
-### Platform matrix
+## Platform matrix
 
 | Platform | Shell | Status |
 |:--|:--|:--|
@@ -111,29 +138,6 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 | Linux | — (browser / PWA to the core) | Not planned |
 | Termux / phone / tablet | — (headless / PWA to the core) | Covered by remote core access |
 
-## Usage
-
-1. Start `dsh web` (or configure a remote service address).
-2. Launch the shell: it auto-detects local 3080 — loads the page if the backend is up, otherwise shows the "backend offline" screen where you can start it in one click.
-3. Drag the window by its top area (right side reserved for native buttons); close minimizes to tray by default.
-
-**All backend controls live in the tray** — the main window stays a pure shell:
-
-- Start / restart / stop the backend (with progress dialogs; stopping really
-  shuts down the service on 3080, including externally started instances)
-- Auto-detect backend · set the backend install folder (auto-detect default)
-- Reload window · check for updates · repo homepage
-
-**Window reliability (Edge-style instant refresh):**
-
-- Shows immediately on launch, never waits for the backend
-- While the backend is down, a local "backend offline" screen is shown and
-  re-probed; the real page loads automatically the moment it answers
-- 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
-
 ## Development
 
 ```sh

package/README.md

@@ -29,6 +29,25 @@
 | **视觉改造** | 自绘标题栏 / 毛玻璃等 | **零改造**，纯净窗口壳 |
 | **跟随上游** | 固定版本 | **跟随 rc.7** |
 
+## 使用
+
+1. 若安装过插件，命令行启动 `dsh` 自动弹出桌面窗口；也可通过插件创建的桌面快捷方式双击，媲美原生桌面端的体验。
+2. 使用原网页端的一切功能。
+3. 托盘右键可以进行详细设置。主窗口不添加任何控件，保持页面纯净。
+
+**后端的一切操作都在托盘右键**，主窗口保持纯壳：
+
+- 启动 / 重启 / 关闭后端（带进度弹窗；关闭会真正停掉 3080 上的服务，包括外部启动的实例）
+- 自动探测后端 · 设置后端安装文件夹（默认自动探测定位）
+- 刷新窗口 · 创建桌面快捷方式 · 检查更新 · 仓库主页
+
+**窗口的可靠性（Edge 式即时刷新）**：
+
+- 双击启动立即出窗，不等后端就绪
+- 后端没起来时显示「后端未连接」页，自动探测；后端一通立即加载
+- 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
+- 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
+
 ## 安装
 
 **方式一：从 Release 下载安装包（想要独立桌面应用的用户）**
@@ -91,21 +110,27 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 ## 架构
 
 ```
-        ┌──────────────────── 内核（dsh web / headless 服务） ────────────────────┐
-        │  会话 · Agent · 插件 · 记忆 都在这层，与界面解耦                          │
-        └─────────────────────────────────────────────────────────────────────────┘
-                              ▲
-              ┌───────────────┴───────────────┐
-              │   dsh-clean-desktop-shell      │
-              │   Electron 壳（客户端）          │
-              │   托盘 · 单实例       │
-              └────────────────────────────────┘
+        ┌────────────── 内核（dsh web / headless 服务）──────────────┐
+        │     会话 · Agent · 插件 · 记忆 都在这层，与界面解耦          │
+        └───────────────────────────┬──────────────────────────────┘
+                                    │  http://127.0.0.1:3080（或远程地址）
+                                    ▼
+        ┌───────────────────────────────────────────────────────────┐
+        │            dsh-clean-desktop-shell（Electron 壳）          │
+        │       托盘 · 单实例 · 离线自动重连 · 桌面快捷方式            │
+        │                                                           │
+        │    同一份壳代码，两种分发形态：                              │
+        │     ├─ 安装包版：独立 exe，双击即用，自动更新                │
+        │     └─ 插件版：随 dsh web 启动自动弹窗（自管 Electron 运行时）│
+        └───────────────────────────────────────────────────────────┘
 ```
 
+- **壳 / 内核分离**：壳只负责窗口、托盘、后端管理；会话、Agent、插件、记忆都在内核层，与界面解耦。
 - **默认**：加载本地 `127.0.0.1:3080`（已配置好的 web profile，零迁移）。
 - **可配远程**：在设置里填入任意远程 DSH 地址，壳只当窗口——手机 / Linux / 其他设备通过浏览器或 PWA 也能接入内核，壳本身不绑定本地服务。
+- **同一套壳代码，两种分发形态**：安装包版（独立 exe）与插件版（随 `dsh web` 启动）共用 `electron/` 壳代码，仅运行时来源与启动方式不同（见「安装」）。
 
-### 平台矩阵
+## 平台矩阵
 
 | 平台 | 壳 | 状态 |
 |:--|:--|:--|
@@ -114,25 +139,6 @@ Unblock-File -Path "$env:USERPROFILE\Downloads\DSH-Clean-Desktop-Shell-Setup-*.e
 | Linux | —（浏览器 / PWA 直连内核） | 不做 |
 | Termux / 手机 / 平板 | —（headless / PWA 直连内核） | 由内核远程访问支持 |
 
-## 使用
-
-1. 启动 `dsh web`（或配置远程服务地址）。
-2. 启动桌面壳：自动检测本地 3080——后端在跑则直接加载，未运行则显示「后端未连接」页，可在离线页一键启动。
-3. 窗口顶部（右侧留系统按钮）可拖动窗口；关闭默认缩到托盘。
-
-**后端的一切操作都在托盘右键**，主窗口保持纯壳：
-
-- 启动 / 重启 / 关闭后端（带进度弹窗；关闭会真正停掉 3080 上的服务，包括外部启动的实例）
-- 自动探测后端 · 设置后端安装文件夹（默认自动探测定位）
-- 刷新窗口 · 检查更新 · 仓库主页
-
-**窗口的可靠性（Edge 式即时刷新）**：
-
-- 双击启动立即出窗，不等后端就绪
-- 后端没起来时显示「后端未连接」页，自动探测；后端一通立即加载
-- 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
-- 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
-
 ## 开发
 
 ```sh

package/electron/update.js

@@ -10,11 +10,27 @@
  * this project does not have yet).
  */
 import { app, shell, dialog } from 'electron'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { showProgress, setProgress, closeProgress } from './progress.js'
+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'
 
+// 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
+// from its package.json instead.
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version
+  } catch {
+    return null
+  }
+})()
+
 let autoUpdater = null
 let updaterPromise = null
 
@@ -111,17 +127,20 @@ export async function checkForUpdatesAuto() {
 
   // Manual path (macOS / dev mode): compare versions, offer GitHub page.
   const r = await checkForUpdate()
+  const isPlugin = !app.isPackaged
   if (r.hasUpdate) {
     const choice = dialog.showMessageBoxSync({
       type: 'info',
       title: '发现新版本',
       message: `当前版本 ${r.current}，最新版本 ${r.latest}。`,
-      detail: 'macOS 自动更新需要代码签名，当前请前往 GitHub Releases 手动下载。',
-      buttons: ['前往下载', '取消'],
+      detail: isPlugin
+        ? '插件形态请到 DSH 网页的「设置 → 插件市场 → 已安装」里点「更新」，完成后按提示重启即可生效。'
+        : 'macOS 自动更新需要代码签名，当前请前往 GitHub Releases 手动下载。',
+      buttons: isPlugin ? ['打开 DSH 网页', '稍后'] : ['前往下载', '取消'],
       defaultId: 0,
       cancelId: 1,
     })
-    if (choice === 0) openUrl(r.url)
+    if (choice === 0) openUrl(isPlugin ? loadConfig().targetUrl : r.url)
   } else if (r.latest) {
     dialog.showMessageBoxSync({
       type: 'info',
@@ -144,6 +163,15 @@ function parseVersion(v) {
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
 }
 
+/**
+ * Current app version. Packaged builds carry it in the exe; a bare runtime
+ * (plugin mode) must read the plugin package.json — app.getVersion() would
+ * report the Electron runtime version there.
+ */
+function currentVersion() {
+  return app.isPackaged ? app.getVersion() : PKG_VERSION || app.getVersion()
+}
+
 /** True when a is strictly newer than b. */
 function isNewer(a, b) {
   if (!a || !b) return false
@@ -158,7 +186,7 @@ function isNewer(a, b) {
  * @returns {{ hasUpdate: boolean, latest?: string, current: string, url: string }}
  */
 export async function checkForUpdate() {
-  const current = app.getVersion()
+  const current = currentVersion()
   let latest = null
   let tag = null
   let url = REPO_URL

package/lib/common.js

@@ -0,0 +1,22 @@
+/**
+ * Shared constants and helpers for the host half modules.
+ *
+ * These compiled files sit at lib/<name>.js, so two dirname hops reach the
+ * package root — the same layout as src/host/ before build, and the same
+ * location electron/ and build/ live in the published package.
+ */
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+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 ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
+export const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
+
+/** 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')
+}

package/lib/icon.js

@@ -0,0 +1,63 @@
+/**
+ * Patch the runtime electron.exe's icon resource so the Windows taskbar
+ * shows our whale icon.
+ *
+ * A bare runtime exe ships Electron's default icon and — as documented —
+ * no runtime API (BrowserWindow icon, setAppDetails, AUMID shortcuts) can
+ * change the taskbar button: it reads the exe's icon resource. rcedit
+ * (electron team's official tool) rewrites it in place.
+ *
+ * Best-effort: icon patching must never block the shell from launching.
+ * Idempotent: a marker file next to the exe records success; a re-provisioned
+ * (new version) exe has no marker and gets patched again.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PKG_ROOT, isWin, runtimeRoot } from './common.js'
+
+export async function patchExeIcon(ctx, exe) {
+  if (!isWin) return
+  const ico = join(PKG_ROOT, 'build', 'icon.ico')
+  if (!existsSync(ico)) return
+  const marker = `${exe}.whale-icon`
+  if (existsSync(marker)) return
+
+  // rcedit is a single self-contained exe, cached next to the runtimes.
+  const rcedit = join(runtimeRoot(), 'rcedit-x64.exe')
+  if (!existsSync(rcedit)) {
+    const url = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
+    ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
+    if (!(await fetchFile(url, rcedit))) {
+      ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
+      return
+    }
+  }
+
+  const child = spawn(rcedit, [exe, '--set-icon', ico], {
+    windowsHide: true,
+    stdio: 'ignore',
+  })
+  const ok = await new Promise((resolve) => {
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+  if (ok) {
+    writeFileSync(marker, String(Date.now()), 'utf8')
+    ctx.logger.info('[clean-desktop-shell] taskbar icon patched (rcedit)')
+  } else {
+    ctx.logger.warn('[clean-desktop-shell] rcedit patch failed — taskbar icon stays default')
+  }
+}
+
+function fetchFile(url, dest) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      'curl',
+      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', '600', '-o', dest, url],
+      { windowsHide: true, stdio: 'ignore' },
+    )
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+}

package/lib/index.js

@@ -4,44 +4,14 @@
  * Branch 2 (plugin-market distribution): when installed through the DSH
  * plugin market, this host half brings up the Electron shell itself.
  *
- * The electron runtime is NOT an npm dependency (electron-builder forbids
- * electron in "dependencies", and pnpm's allowBuilds would block its
- * postinstall anyway). Instead the host half manages the runtime on its
- * own, under $DSH_HOME/desktop-shell-runtime/:
- *
- *   1. resolve the version to run (package.json → desktopShell.electronVersion)
- *   2. if that version dir exists → reuse it
- *   3. otherwise download the electron zip from the best source for the
- *      network (official GitHub releases vs npmmirror mirror), extract it,
- *      and drop any older version dirs (no unbounded disk growth)
- *   4. spawn the shell (runtime electron + electron/main.js) — the same
- *      code branch 1 (installer) ships
- *
- * Window, tray, backend management etc. are identical to branch 1; only
- * the runtime provisioning differs.
+ * The shell code is shared with branch 1 (installer) — only the runtime
+ * provisioning and launch differ. See runtime.js (provisioning) and
+ * icon.js (Windows taskbar icon).
  */
 import { spawn } from 'node:child_process'
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
-const MAIN_JS = join(PKG_ROOT, 'electron', 'main.js')
-const isWin = process.platform === 'win32'
-const EXE_NAME = isWin ? 'electron.exe' : 'electron'
-const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
-const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
+import { PKG_ROOT, MAIN_JS } from './common.js'
+import { ensureRuntime } from './runtime.js'
+import { patchExeIcon } from './icon.js'
 
 // cordis registers the plugin by this name — bundles without an explicit
 // `name` export are silently skipped by the dsh loader.
@@ -63,6 +33,7 @@ export function apply(ctx) {
   ;(async () => {
     try {
       const exe = await ensureRuntime(ctx)
+      await patchExeIcon(ctx, exe).catch(() => {})
       launchShell(exe, ctx)
     } catch (err) {
       ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
@@ -70,246 +41,6 @@ export function apply(ctx) {
   })()
 }
 
-// ---------- electron runtime provisioning ----------
-
-function electronVersion() {
-  try {
-    const meta = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
-    return meta.desktopShell?.electronVersion || null
-  } catch {
-    return null
-  }
-}
-
-function runtimeRoot() {
-  return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'desktop-shell-runtime')
-}
-
-function versionDir(root, version) {
-  return join(root, `electron-v${version}`)
-}
-
-function zipName(version) {
-  return `electron-v${version}-${PLATFORM}-${ARCH}.zip`
-}
-
-async function ensureRuntime(ctx) {
-  const version = electronVersion()
-  if (!version) throw new Error('desktopShell.electronVersion missing in package.json')
-  const root = runtimeRoot()
-  const dir = versionDir(root, version)
-  const exe = join(dir, EXE_NAME)
-
-  // 1) Already provisioned for this version?
-  if (existsSync(exe)) {
-    cleanupOldVersions(root, dir)
-    await patchExeIcon(ctx, exe, root).catch(() => {})
-    return exe
-  }
-
-  // 2) Local reuse: DSH_SHELL_ELECTRON_DIR → link/copy its dist/ (fast).
-  const localSrc = process.env.DSH_SHELL_ELECTRON_DIR
-  if (localSrc) {
-    const srcExe = join(localSrc, 'dist', EXE_NAME)
-    if (existsSync(srcExe) && provisionLocalDist(localSrc, dir)) {
-      ctx.logger.info(`[clean-desktop-shell] reused electron runtime from ${localSrc}`)
-    }
-  }
-
-  // 3) Download + extract the official zip from a network-appropriate source.
-  if (!existsSync(exe)) {
-    mkdirSync(root, { recursive: true })
-    await downloadRuntime(ctx, version, root, dir)
-  }
-
-  if (!existsSync(exe)) {
-    throw new Error(
-      'electron runtime provisioning failed — check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
-    )
-  }
-  cleanupOldVersions(root, dir)
-  ctx.logger.info(`[clean-desktop-shell] electron runtime ${version} ready at ${dir}`)
-  await patchExeIcon(ctx, exe, root).catch(() => {})
-  return exe
-}
-
-/**
- * Patch the runtime electron.exe's icon resource so the Windows taskbar
- * shows our whale icon. A bare runtime exe ships Electron's default icon
- * and — as documented — no runtime API (BrowserWindow icon, setAppDetails,
- * AUMID shortcuts) can change the taskbar button: it reads the exe's icon
- * resource. rcedit (electron team's official tool) rewrites it in place.
- *
- * Best-effort: icon patching must never block the shell from launching.
- * Idempotent: a marker file next to the exe records success; a re-provisioned
- * (new version) exe has no marker and gets patched again.
- */
-async function patchExeIcon(ctx, exe, root) {
-  if (!isWin) return
-  const ico = join(PKG_ROOT, 'build', 'icon.ico')
-  if (!existsSync(ico)) return
-  const marker = `${exe}.whale-icon`
-  if (existsSync(marker)) return
-
-  // rcedit is a single self-contained exe, cached next to the runtimes.
-  const rcedit = join(root, 'rcedit-x64.exe')
-  if (!existsSync(rcedit)) {
-    const url = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
-    ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
-    if (!(await fetchFile(url, rcedit))) {
-      ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
-      return
-    }
-  }
-
-  const child = spawn(rcedit, [exe, '--set-icon', ico], {
-    windowsHide: true,
-    stdio: 'ignore',
-  })
-  const ok = await new Promise((resolve) => {
-    child.on('error', () => resolve(false))
-    child.on('exit', (code) => resolve(code === 0))
-  })
-  if (ok) {
-    writeFileSync(marker, String(Date.now()), 'utf8')
-    ctx.logger.info('[clean-desktop-shell] taskbar icon patched (rcedit)')
-  } else {
-    ctx.logger.warn('[clean-desktop-shell] rcedit patch failed — taskbar icon stays default')
-  }
-}
-
-async function downloadRuntime(ctx, version, root, dir) {
-  const tmpZip = join(root, `.electron-${version}.zip.tmp`)
-  rmSync(tmpZip, { force: true })
-  const urls = await runtimeUrls(version)
-  for (const url of urls) {
-    ctx.logger.info(`[clean-desktop-shell] downloading electron ${version} from ${url}`)
-    if (await fetchFile(url, tmpZip)) {
-      // Zip extracts to an inner dir named like the zip basename.
-      const inner = join(root, zipName(version).replace(/\.zip$/, ''))
-      try {
-        await extractZip(tmpZip, root)
-        if (existsSync(join(inner, EXE_NAME)) && inner !== dir) {
-          rmSync(dir, { recursive: true, force: true })
-          renameSync(inner, dir)
-        }
-        rmSync(tmpZip, { force: true })
-        return
-      } catch (err) {
-        ctx.logger.warn(`[clean-desktop-shell] extract failed: ${err?.message ?? err}`)
-        rmSync(inner, { recursive: true, force: true })
-      }
-    }
-    // Failed download — drop the partial file so a later run starts clean.
-    rmSync(tmpZip, { force: true })
-  }
-  throw new Error('electron download failed from all sources')
-}
-
-/**
- * Pick the download source by racing a HEAD probe against each candidate
- * (direct connection, 3s each). The fastest reachable source goes first —
- * this naturally prefers the domestic npmmirror mirror on CN networks,
- * the official GitHub source on international/well-proxied networks, and
- * never wastes a full download on a dead source.
- */
-async function runtimeUrls(version) {
-  const candidates = [
-    { name: 'github', url: `https://github.com/electron/electron/releases/download/v${version}/${zipName(version)}` },
-    { name: 'npmmirror', url: `https://npmmirror.com/mirrors/electron/${version}/${zipName(version)}` },
-  ]
-  const results = await Promise.all(
-    candidates.map(async (c) => {
-      const t0 = Date.now()
-      try {
-        const ctrl = new AbortController()
-        const timer = setTimeout(() => ctrl.abort(), 3000)
-        const res = await fetch(c.url, { signal: ctrl.signal, method: 'HEAD' })
-        clearTimeout(timer)
-        if (res.status < 500) return { ...c, ms: Date.now() - t0 }
-      } catch {
-        // unreachable — drop
-      }
-      return null
-    }),
-  )
-  const ok = results.filter(Boolean).sort((a, b) => a.ms - b.ms)
-  if (ok.length === 0) {
-    // Probes all failed (offline?) — still try both, mirror first (cheap).
-    return [candidates[1].url, candidates[0].url]
-  }
-  const rest = candidates.map((c) => c.url).filter((u) => u !== ok[0].url)
-  return [ok[0].url, ...rest]
-}
-
-function fetchFile(url, dest) {
-  return new Promise((resolve) => {
-    // curl is available on Windows 10+; streams to disk, honors proxy env.
-    // --max-time keeps a stalled download from hanging forever (a proxy
-    // stall previously left a half-written .zip.tmp and blocked the shell
-    // launch); --retry 2 rides out transient failures.
-    const child = spawn(
-      'curl',
-      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', '600', '-o', dest, url],
-      { windowsHide: true, stdio: 'ignore' },
-    )
-    child.on('error', () => resolve(false))
-    child.on('exit', (code) => resolve(code === 0))
-  })
-}
-
-function extractZip(zipPath, dest) {
-  // Windows ships bsdtar (tar.exe) which reads zip; fall back to
-  // PowerShell Expand-Archive if needed.
-  const child = spawn('tar', ['-xf', zipPath, '-C', dest], { windowsHide: true, stdio: 'ignore' })
-  return new Promise((resolve, reject) => {
-    child.on('error', reject)
-    child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`tar exit ${code}`))))
-  })
-}
-
-/** Remove version dirs older than the current one (dead weight). */
-function cleanupOldVersions(root, currentDir) {
-  try {
-    for (const entry of readdirSync(root)) {
-      if (!entry.startsWith('electron-v')) continue
-      const full = join(root, entry)
-      if (full === currentDir) continue
-      rmSync(full, { recursive: true, force: true })
-    }
-  } catch {
-    // best-effort
-  }
-}
-
-/**
- * Provision a local electron package's dist/ as the version dir itself,
- * so the layout matches a downloaded runtime: <dir>/electron(.exe) at the
- * version-dir root. Windows: junction (zero-copy, instant) — a 269MB
- * recursive cpSync can be killed by sandbox/AV on large trees, so only
- * fall back to a copy.
- */
-function provisionLocalDist(srcPkg, destDir) {
-  if (isWin) {
-    try {
-      rmSync(destDir, { recursive: true, force: true })
-      symlinkSync(join(srcPkg, 'dist'), destDir, 'junction')
-      return true
-    } catch {
-      // fall through to a real copy
-    }
-  }
-  try {
-    rmSync(destDir, { recursive: true, force: true })
-    cpSync(join(srcPkg, 'dist'), destDir, { recursive: true })
-    return true
-  } catch {
-    return false
-  }
-}
-
-// ---------- shell launch ----------
-
 function launchShell(exe, ctx) {
   if (launched) return
   const child = spawn(exe, [MAIN_JS], {