dsh-clean-desktop-shell 0.1.1 → 0.1.3

package/electron/main.js

@@ -8,11 +8,13 @@
  *
  * The main window is a pure shell — all backend controls live in the tray.
  */
-import { app, BrowserWindow } from 'electron'
+import { app, BrowserWindow, dialog } from 'electron'
 import { createMainWindow, reloadWindow } from './window.js'
 import { createTray, refreshTrayMenu } from './tray.js'
 import { loadConfig, saveConfig } from './config.js'
-import { detect, start } from './service.js'
+import { detect } from './service.js'
+import { setupAutoUpdater } from './update.js'
+import { shortcutSupported, hasDesktopShortcut, createDesktopShortcut } from './shortcut.js'
 
 const isMac = process.platform === 'darwin'
 
@@ -22,6 +24,11 @@ if (process.platform === 'win32') {
   app.setAppUserModelId('com.icather.dsh-clean-desktop-shell')
 }
 
+// Uniform userData across both distribution branches (installer vs
+// plugin-market), so config (target URL, backend path, ...) is shared
+// no matter how the shell was launched.
+app.setName('DSH Clean Desktop Shell')
+
 /** Single instance: a second launch just focuses the existing window. */
 const gotLock = app.requestSingleInstanceLock()
 if (!gotLock) {
@@ -56,26 +63,48 @@ if (!gotLock) {
     return mainWindow
   }
 
-  /** Launch-time backend bootstrap: detect, and auto-start when local. */
+  /**
+   * Launch-time backend detection. Detects whether a local dsh web is
+   * already running so the tray and window reflect the real state, but
+   * never auto-starts it — starting is a manual action (tray menu or the
+   * offline screen button) so it cannot fight an explicit "stop".
+   */
   async function bootstrapBackend() {
     const config = loadConfig()
     const target = config.targetUrl || 'http://127.0.0.1:3080'
-    const isLocalDefault = target === 'http://127.0.0.1:3080'
-    if (!isLocalDefault || config.autoStartService === false) return
-
-    const url = await detect()
-    if (!url) {
-      // Not running — try to start it, but never block window opening.
-      try {
-        await start({ backendPath: config.backendPath })
-      } catch {
-        // Backend unavailable; window still opens, tray shows the error.
-      }
-    }
+    // Remote targets are the user's own business — never probe local.
+    if (target !== 'http://127.0.0.1:3080') return
+    await detect()
     // Reflect the post-detect state in the tray menu.
     refreshTrayMenu()
   }
 
+  /**
+   * First-run desktop shortcut prompt (Windows packaged apps only).
+   * Asks once; the tray "create desktop shortcut" item stays available
+   * forever, so saying no is never a dead end.
+   */
+  async function ensureShortcut() {
+    if (!shortcutSupported() || loadConfig().shortcutAsked) return
+    saveConfig({ ...loadConfig(), shortcutAsked: true })
+    if (await hasDesktopShortcut()) return
+    const choice = dialog.showMessageBoxSync({
+      type: 'question',
+      title: '创建桌面快捷方式？',
+      message: '是否在桌面创建「DSH Clean Desktop Shell」快捷方式？',
+      detail: '选择「跳过」也不影响使用——之后可随时在托盘右键菜单中一键添加。',
+      buttons: ['创建', '跳过'],
+      defaultId: 0,
+      cancelId: 1,
+    })
+    if (choice === 0) {
+      const ok = await createDesktopShortcut()
+      if (!ok) {
+        dialog.showErrorBox('创建快捷方式失败', '无法在桌面创建快捷方式。可稍后在托盘右键菜单中重试。')
+      }
+    }
+  }
+
   app.whenReady().then(async () => {
     await createWindow()
     tray = createTray({
@@ -84,11 +113,6 @@ if (!gotLock) {
         mainWindow.show()
         mainWindow.focus()
       },
-      onToggleAutoStart: (enabled) => {
-        const config = loadConfig()
-        saveConfig({ ...config, autoLaunch: enabled })
-        app.setLoginItemSettings({ openAtLogin: enabled })
-      },
       onReload: () => {
         if (mainWindow && !mainWindow.isDestroyed()) {
           reloadWindow(mainWindow, loadConfig().targetUrl || 'http://127.0.0.1:3080')
@@ -103,6 +127,12 @@ if (!gotLock) {
     // Backend bootstrap in background (never delays the window).
     bootstrapBackend().catch(() => {})
 
+    // Windows: wire the auto-updater (downloads new installers silently).
+    setupAutoUpdater()
+
+    // First run: offer a desktop shortcut (never nags twice).
+    ensureShortcut().catch(() => {})
+
     app.on('activate', () => {
       if (BrowserWindow.getAllWindows().length === 0) createWindow()
       else mainWindow?.show()

package/electron/shortcut.js

@@ -0,0 +1,72 @@
+/**
+ * Desktop shortcut management (Windows .lnk via WScript.Shell).
+ *
+ * Used by:
+ *  - first-run prompt in main.js ("create a desktop shortcut?")
+ *  - the tray "create desktop shortcut" item (always available)
+ *
+ * Only meaningful for packaged apps — in dev mode there is no stable
+ * executable to point the shortcut at, so the feature is disabled there.
+ */
+import { app } from 'electron'
+import { spawn } from 'node:child_process'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const isWin = process.platform === 'win32'
+const SHORTCUT_NAME = 'DSH Clean Desktop Shell.lnk'
+
+/** Shortcuts are a Windows packaged-app feature. */
+export function shortcutSupported() {
+  return isWin && app.isPackaged
+}
+
+function ps(str) {
+  return "'" + String(str).replace(/'/g, "''") + "'"
+}
+
+function runPs(script) {
+  return new Promise((resolve) => {
+    const p = spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+      windowsHide: true,
+    })
+    let out = ''
+    p.stdout.on('data', (d) => {
+      out += d.toString()
+    })
+    p.on('error', () => resolve(null))
+    p.on('exit', () => resolve(out))
+  })
+}
+
+/** True when a desktop shortcut already points at this app's exe. */
+export async function hasDesktopShortcut() {
+  if (!isWin) return false
+  const script =
+    `$ws = New-Object -ComObject WScript.Shell; ` +
+    `Get-ChildItem ${ps(join(homedir(), 'Desktop', '*.lnk'))} | ` +
+    `ForEach-Object { $ws.CreateShortcut($_.FullName).TargetPath }`
+  const out = await runPs(script)
+  if (out === null) return false
+  const target = process.execPath.toLowerCase()
+  return out
+    .split(/\r?\n/)
+    .map((s) => s.trim().toLowerCase())
+    .some((line) => line === target)
+}
+
+/** Create (or overwrite) the desktop shortcut for this app. Returns bool. */
+export async function createDesktopShortcut() {
+  if (!shortcutSupported()) return false
+  const target = process.execPath
+  const lnk = join(homedir(), 'Desktop', SHORTCUT_NAME)
+  const script =
+    `$ws = New-Object -ComObject WScript.Shell; ` +
+    `$s = $ws.CreateShortcut(${ps(lnk)}); ` +
+    `$s.TargetPath = ${ps(target)}; ` +
+    `$s.WorkingDirectory = ${ps(dirname(target))}; ` +
+    `$s.IconLocation = ${ps(`${target},0`)}; ` +
+    `$s.Save()`
+  const out = await runPs(script)
+  return out !== null
+}

package/electron/tray.js

@@ -19,7 +19,8 @@ import {
   onStatusChange,
 } from './service.js'
 import { showProgress, setProgress, closeProgress } from './progress.js'
-import { checkForUpdate, openRepo, openUrl } from './update.js'
+import { checkForUpdate, checkForUpdatesAuto, isAutoUpdateSupported, openRepo, openUrl } from './update.js'
+import { shortcutSupported, createDesktopShortcut } from './shortcut.js'
 
 const trayIconPath = join(
   fileURLToPath(new URL('.', import.meta.url)),
@@ -30,10 +31,10 @@ const trayIconPath = join(
 let trayInstance = null
 let handlers = null
 
-export function createTray({ onShow, onToggleAutoStart, onReload, onQuit }) {
+export function createTray({ onShow, onReload, onQuit }) {
   const icon = nativeImage.createFromPath(trayIconPath)
 
-  handlers = { onShow, onToggleAutoStart, onReload, onQuit }
+  handlers = { onShow, onReload, onQuit }
 
   trayInstance = new Tray(icon)
   trayInstance.setToolTip('DSH Clean Desktop Shell')
@@ -50,7 +51,7 @@ export function createTray({ onShow, onToggleAutoStart, onReload, onQuit }) {
 /** Rebuild the context menu (call after backend state changes). */
 export function refreshTrayMenu() {
   if (!trayInstance || !handlers) return
-  const { onShow, onToggleAutoStart, onReload, onQuit } = handlers
+  const { onShow, onReload, onQuit } = handlers
   const st = getStatus()
   const label = statusLabel(st)
 
@@ -60,6 +61,26 @@ export function refreshTrayMenu() {
       label: '刷新窗口',
       click: onReload,
     },
+    {
+      label: '创建桌面快捷方式',
+      enabled: shortcutSupported(),
+      click: async () => {
+        const ok = await createDesktopShortcut()
+        if (ok) {
+          dialog.showMessageBoxSync({
+            type: 'info',
+            title: '已创建',
+            message: '桌面快捷方式已创建。',
+          })
+        } else {
+          dialog.showMessageBoxSync({
+            type: 'warning',
+            title: '创建失败',
+            message: '无法创建桌面快捷方式，请稍后重试。',
+          })
+        }
+      },
+    },
     { type: 'separator' },
     { label: `后端：${label}`, enabled: false },
     {
@@ -115,6 +136,12 @@ export function refreshTrayMenu() {
     {
       label: '检查更新…',
       click: async () => {
+        // Windows (packaged): auto-download + install on restart.
+        // macOS / dev mode: manual page link (macOS needs a signature).
+        if (isAutoUpdateSupported()) {
+          await checkForUpdatesAuto()
+          return
+        }
         const r = await checkForUpdate()
         if (r.hasUpdate) {
           const choice = dialog.showMessageBoxSync({
@@ -147,13 +174,6 @@ export function refreshTrayMenu() {
       click: () => openRepo(),
     },
     { type: 'separator' },
-    {
-      label: '开机自启',
-      type: 'checkbox',
-      checked: !!loadConfig().autoLaunch,
-      click: (item) => onToggleAutoStart(item.checked),
-    },
-    { type: 'separator' },
     { label: '退出', click: onQuit },
   ])
   trayInstance.setContextMenu(menu)

package/electron/update.js

@@ -1,15 +1,142 @@
 /**
- * Version check and repo links.
+ * Update handling — Windows auto-update, macOS manual download.
  *
- * Checks the latest GitHub release of dsh-clean-desktop-shell against the
- * local app version (from app.getVersion()). Network failures are treated
- * as "no update" — never block or error in the tray.
+ * Windows (packaged app): uses electron-updater to download the new
+ * installer from GitHub Releases in the background and install it on
+ * restart. Progress is shown in the small progress window.
+ *
+ * macOS / dev mode: falls back to a manual check that opens the GitHub
+ * Releases page (macOS auto-update needs a Developer ID signature which
+ * this project does not have yet).
  */
-import { app, shell } from 'electron'
+import { app, shell, dialog } from 'electron'
+import { showProgress, setProgress, closeProgress } from './progress.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'
 
+let autoUpdater = null
+let updaterPromise = null
+
+/** Lazy-load electron-updater (CJS → ESM interop via dynamic import). */
+function getAutoUpdater() {
+  if (!updaterPromise) {
+    updaterPromise = import('electron-updater').then((m) => m.autoUpdater)
+  }
+  return updaterPromise
+}
+
+/** Windows packaged apps can auto-update; everything else uses manual. */
+export function isAutoUpdateSupported() {
+  return process.platform === 'win32' && app.isPackaged
+}
+
+/** Wire the auto-updater events once (no-op on mac / dev mode). */
+export function setupAutoUpdater() {
+  if (!isAutoUpdateSupported()) return
+  getAutoUpdater()
+    .then((au) => {
+      if (autoUpdater) return
+      autoUpdater = au
+      autoUpdater.autoDownload = true
+      autoUpdater.autoInstallOnAppQuit = true
+
+      autoUpdater.on('update-available', () => {
+        showProgress({ title: '检查更新', message: '发现新版本，正在后台下载…' })
+      })
+      autoUpdater.on('download-progress', (p) => {
+        const pct = Math.round(p.percent)
+        setProgress({
+          title: '检查更新',
+          message: `正在下载更新：${pct}%`,
+          state: pct >= 100 ? 'ok' : 'busy',
+        })
+      })
+      autoUpdater.on('update-downloaded', () => {
+        setProgress({ title: '检查更新', message: '更新已下载', state: 'ok' })
+        setTimeout(() => {
+          closeProgress()
+          const choice = dialog.showMessageBoxSync({
+            type: 'info',
+            title: '更新已就绪',
+            message: '新版本已下载完成，重启应用即可安装。',
+            detail: '是否立即重启安装？',
+            buttons: ['立即重启', '稍后'],
+            defaultId: 0,
+            cancelId: 1,
+          })
+          if (choice === 0) autoUpdater.quitAndInstall()
+        }, 800)
+      })
+      autoUpdater.on('update-not-available', () => {
+        closeProgress()
+        dialog.showMessageBoxSync({
+          type: 'info',
+          title: '已是最新版本',
+          message: '当前已是最新版本。',
+        })
+      })
+      autoUpdater.on('error', (err) => {
+        closeProgress()
+        dialog.showMessageBoxSync({
+          type: 'warning',
+          title: '检查更新失败',
+          message: `自动更新失败：${err?.message || '未知错误'}`,
+          detail: '可前往 GitHub Releases 手动下载。',
+        })
+      })
+    })
+    .catch(() => {
+      // electron-updater failed to load — auto-update silently disabled.
+    })
+}
+
+/** Tray "check for update": auto flow on Windows, manual fallback elsewhere. */
+export async function checkForUpdatesAuto() {
+  if (isAutoUpdateSupported()) {
+    try {
+      await getAutoUpdater()
+      await autoUpdater?.checkForUpdates()
+    } catch (err) {
+      closeProgress()
+      dialog.showMessageBoxSync({
+        type: 'warning',
+        title: '检查更新失败',
+        message: `自动更新失败：${err?.message || '未知错误'}`,
+        detail: '可前往 GitHub Releases 手动下载。',
+      })
+    }
+    return
+  }
+
+  // Manual path (macOS / dev mode): compare versions, offer GitHub page.
+  const r = await checkForUpdate()
+  if (r.hasUpdate) {
+    const choice = dialog.showMessageBoxSync({
+      type: 'info',
+      title: '发现新版本',
+      message: `当前版本 ${r.current}，最新版本 ${r.latest}。`,
+      detail: 'macOS 自动更新需要代码签名，当前请前往 GitHub Releases 手动下载。',
+      buttons: ['前往下载', '取消'],
+      defaultId: 0,
+      cancelId: 1,
+    })
+    if (choice === 0) openUrl(r.url)
+  } else if (r.latest) {
+    dialog.showMessageBoxSync({
+      type: 'info',
+      title: '已是最新版本',
+      message: `当前版本 ${r.current} 已是最新（${r.latest}）。`,
+    })
+  } else {
+    dialog.showMessageBoxSync({
+      type: 'warning',
+      title: '检查更新失败',
+      message: '无法连接 GitHub 检查更新，请检查网络后重试。',
+    })
+  }
+}
+
 /** Parse "v1.2.3" / "1.2.3" → [1,2,3]; null when malformed. */
 function parseVersion(v) {
   if (!v) return null
@@ -27,7 +154,7 @@ function isNewer(a, b) {
 }
 
 /**
- * Check for a newer release.
+ * Manual version check against the latest GitHub release (macOS path).
  * @returns {{ hasUpdate: boolean, latest?: string, current: string, url: string }}
  */
 export async function checkForUpdate() {

package/lib/index.js

@@ -1,13 +1,247 @@
 /**
  * dsh-clean-desktop-shell — host half (plugin loader entry).
  *
- * The desktop shell is an Electron client; the host half only registers
- * the plugin so it mounts cleanly into a dsh profile and exposes its
- * settings surface. Window material (Mica / vibrancy) lives in the
- * Electron main process (see src/main/).
+ * 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.
  */
+import { spawn } from 'node:child_process'
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+} 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'
+
+// Disable auto-launch with DSH_SHELL_AUTO_LAUNCH=0.
+const AUTO_LAUNCH = process.env.DSH_SHELL_AUTO_LAUNCH !== '0'
+
+let launched = false
+
 export function apply(ctx) {
-  ctx.on('ready', () => {
+  ctx.on('ready', async () => {
     ctx.logger.info('[clean-desktop-shell] mounted (host half)')
+    if (!AUTO_LAUNCH) return
+    try {
+      const exe = await ensureRuntime(ctx)
+      launchShell(exe, ctx)
+    } catch (err) {
+      ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
+    }
+  })
+}
+
+// ---------- 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)
+    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}`)
+  return exe
+}
+
+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 })
+      }
+    }
+  }
+  throw new Error('electron download failed from all sources')
+}
+
+/** Probe GitHub; reachable → official releases, else the npmmirror mirror. */
+async function runtimeUrls(version) {
+  const official = `https://github.com/electron/electron/releases/download/v${version}/${zipName(version)}`
+  const mirror = `https://npmmirror.com/mirrors/electron/${version}/${zipName(version)}`
+  try {
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 3000)
+    const res = await fetch('https://github.com', { signal: ctrl.signal, method: 'HEAD' })
+    clearTimeout(timer)
+    if (res.status < 500) return [official, mirror]
+  } catch {
+    // unreachable — mirror first
+  }
+  return [mirror, official]
+}
+
+function fetchFile(url, dest) {
+  return new Promise((resolve) => {
+    // curl is available on Windows 10+; streams to disk, honors proxy env.
+    const child = spawn('curl', ['-L', '--fail', '--silent', '--show-error', '-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], {
+    cwd: PKG_ROOT,
+    env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined },
+    stdio: 'ignore',
+    windowsHide: false,
+  })
+  launched = true
+  child.on('error', (err) => {
+    launched = false
+    ctx.logger.warn(`[clean-desktop-shell] shell spawn error: ${err.message}`)
+  })
+  child.on('exit', (code) => {
+    launched = false
+    ctx.logger.info(`[clean-desktop-shell] shell exited (${code})`)
   })
 }