dsh-clean-desktop-shell 0.1.9 → 0.1.11

package/README.en.md

@@ -231,6 +231,38 @@ npm run pack    # package NSIS (Win) / DMG (mac)
 
 ## Changelog
 
+### 0.1.10
+- Version comparison now uses semver (`semver.coerce` + `semver.gt`) — the industry standard — replacing the hand-rolled tuple parser.
+- All HTTP timeouts migrated to `AbortSignal.timeout` (standard self-cleaning API, no manual controller leaks).
+- Config persistence switched to atomic writes (tmp + rename); a crash mid-write can no longer truncate config.json.
+- Removed the developer-machine-specific hardcoded path (`D:\deepseek-harness\prod\...`); replaced with config `backendPath` + `DSH_BACKEND_DIR` env var + npm global dir candidates.
+- Windows backend stop now uses `taskkill /T /F` tree kill (the old `proc.kill()` left orphan node children holding the port when the command was a .cmd shim); POSIX falls back through SIGTERM → SIGKILL gracefully.
+- Shortcut management rewritten to Electron-native `shell.writeShortcutLink` / `readShortcutLink`, dropping the PowerShell + WScript COM dependency (also fixes OneDrive Desktop redirection via `app.getPath('desktop')`).
+- New process-level crash guard: `uncaughtException` / `unhandledRejection` append to `userData/shell-crash.log` (128 KB cap with auto-truncation) — attachable in bug reports.
+- Electron runtime zip now verified against SHASUMS256.txt post-download (SHA-256 streaming check); corrupted files are discarded and the next mirror source is tried.
+- Resilience hardening: backend stdout/stderr capped at 64 KB ring buffer; config load type-validates known keys and silently drops unknown ones; offline page detection upgraded from `includes('error.html')` to precise file:// URL comparison.
+- `npm run check` syntax gate expanded from 1 file (lib/index.js) to all 17 shipped JS files.
+
+### 0.1.9
+- One-click "update now" for plugin mode when a new version is found: the
+  installing package manager (pnpm/npm/yarn/bun) is inferred from the lockfile
+  next to the install, and a chain of command variants (with a corepack
+  fallback) absorbs PATH and pnpm version differences. The on-disk version is
+  verified afterwards, with success / unchanged / failure dialogs — failures
+  list the attempted commands and output (copyable).
+- The update dialog also shows a copyable manual command and keeps the DSH
+  market entry; commands run via `shell:true` + `windowsHide` on Windows for
+  `.cmd` shim and PowerShell / cmd compatibility.
+
+### 0.1.8
+- Plugin (npm-installed) mode now checks the npm registry `dist-tags.latest`
+  and compares it against the local version from the same source, instead of
+  wrongly querying GitHub `/releases/latest` (when the GitHub Latest tag
+  lagged behind, this produced the contradictory "current 0.1.7 is up to date
+  (v0.1.6)" dialog).
+- The packaged desktop app still uses GitHub Releases; dropped the redundant
+  version repetition in the "up to date" dialog.
+
 ### 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

package/README.md

@@ -212,6 +212,26 @@ npm run pack    # 打包 NSIS (Win) / DMG (mac)
 
 ## 更新历史
 
+### 0.1.10
+- 版本比较改用 semver（industry-standard `semver.coerce` + `semver.gt`），替换手写元组比较。
+- 所有 HTTP 超时改为 `AbortSignal.timeout`（标准自清理 API，无泄漏风险）。
+- 配置持久化改为原子写入（tmp + rename），崩溃/断电不会留下截断的 config.json。
+- 移除代码中硬编码的 `D:\deepseek-harness\prod\...` 开发机路径：改用 config backendPath + `DSH_BACKEND_DIR` 环境变量 + npm 全局目录候选。
+- Windows 后端进程停止改用 `taskkill /T /F` 树杀（.cmd shim 留下的孤儿 node 进程不再占端口）；POSIX 先 SIGTERM 再 SIGKILL 优雅降级。
+- 快捷方式管理整体替换为 Electron 原生 `shell.writeShortcutLink` / `readShortcutLink`，移除 PowerShell + COM 依赖（顺带修复 OneDrive 桌面重定向问题）。
+- 新增进程级 crash guard：`uncaughtException` / `unhandledRejection` 写入 `userData/shell-crash.log`（128KB 上限自动截断），便于附在 bug 报告中。
+- Electron runtime 下载后新增 SHA-256 完整性校验（对比源站点 SHASUMS256.txt），损坏文件自动跳到下一源重试。
+- 冗余加固：后端 stdout/stderr 缓冲 64KB 环形截断；配置字段类型校验并自动丢弃未知键；窗口离线页检测从 `includes('error.html')` 改为精确 URL 比对。
+- 自检脚本 `npm run check` 扩展到覆盖全部 17 个发布 JS 文件的语法门禁（此前只检查 lib/index.js）。
+
+### 0.1.9
+- 插件形态发现新版本时新增「立即更新」一键更新：从安装位置旁的 lockfile 推断实际使用的包管理器（pnpm/npm/yarn/bun），按命令变体链逐条尝试（含 corepack 兜底），吸收 PATH 与 pnpm 版本差异；更新后校验磁盘版本，成功 / 未变化 / 失败三态弹窗，失败时附已试命令与输出（可复制）。
+- 更新弹窗同时内嵌可复制的手动更新命令，并保留 DSH 插件市场入口；Windows 下经 `shell:true` + `windowsHide` 执行，兼容 `.cmd` shim 与 PowerShell / cmd 环境。
+
+### 0.1.8
+- 插件形态（npm 安装）的更新检查改查 npm registry 的 `dist-tags.latest`，与本地版本同源对比；不再错爬 GitHub `/releases/latest`（此前 GitHub Latest 标记未及时挪动时会弹出「当前 0.1.7 已是最新（v0.1.6）」的自相矛盾提示）。
+- 打包桌面应用仍走 GitHub Releases；修复「已是最新」弹窗括号内重复显示版本号的文案。
+
 ### 0.1.7
 - **修复 macOS 上窗口完全打不开的静默失败**：Electron 的 macOS 包是 `Electron.app` 应用包，可执行文件位于 `Electron.app/Contents/MacOS/Electron`；此前按 Linux 布局去找顶层 `electron`，导致 Mac 上必然启动失败且无任何提示。
 - 解压改为多策略回退（ditto / unzip / tar）并校验产物；解压后补齐可执行位，清除 macOS quarantine 扩展属性。

package/electron/config.js

@@ -2,19 +2,27 @@
  * Shell config persistence (userData/config.json).
  *
  * Fields:
- *  - targetUrl:       default 'http://127.0.0.1:3080' — set to any remote
- *                     DSH address to run the shell as a pure window.
- *  - closeToTray:      default true.
- *  - windowMode:       'advanced' (mica/vibrancy) | 'compatibility'.
+ *  - targetUrl:    DEFAULT_TARGET_URL — set to any remote DSH address to
+ *                  run the shell as a pure window.
+ *  - closeToTray:  default true.
+ *  - backendPath:  folder containing the dsh CLI (tray "set backend folder").
+ *  - shortcutAsked: true once the first-run shortcut prompt was shown.
+ *
+ * Persistence is atomic (tmp file + rename) and load-time type-checked, so
+ * a crash mid-write or a hand-edited file can never poison the shell.
  */
 import { app } from 'electron'
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
+// Single source of truth for the local dsh web endpoint. Every module that
+// needs the default URL or its port imports it from here — no duplicated
+// literals.
+export const DEFAULT_TARGET_URL = 'http://127.0.0.1:3080'
+
 const DEFAULTS = {
-  targetUrl: 'http://127.0.0.1:3080',
+  targetUrl: DEFAULT_TARGET_URL,
   closeToTray: true,
-  windowMode: 'advanced',
   backendPath: null,
   // True once the first-run "create a desktop shortcut?" prompt was shown
   // (so it never nags again). The tray item stays available regardless.
@@ -30,8 +38,14 @@ function configPath() {
 export function loadConfig() {
   if (cached) return cached
   try {
-    const raw = readFileSync(configPath(), 'utf8')
-    cached = { ...DEFAULTS, ...JSON.parse(raw) }
+    const parsed = JSON.parse(readFileSync(configPath(), 'utf8'))
+    // Keep only known fields with expected types — unknown/legacy keys
+    // (e.g. the never-wired `windowMode`) are dropped on the next save.
+    cached = { ...DEFAULTS }
+    if (typeof parsed.targetUrl === 'string' && parsed.targetUrl) cached.targetUrl = parsed.targetUrl
+    if (typeof parsed.closeToTray === 'boolean') cached.closeToTray = parsed.closeToTray
+    if (typeof parsed.backendPath === 'string' || parsed.backendPath === null) cached.backendPath = parsed.backendPath
+    if (typeof parsed.shortcutAsked === 'boolean') cached.shortcutAsked = parsed.shortcutAsked
   } catch {
     cached = { ...DEFAULTS }
   }
@@ -42,6 +56,22 @@ export function saveConfig(next) {
   cached = { ...DEFAULTS, ...next }
   const file = configPath()
   mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, JSON.stringify(cached, null, 2), 'utf8')
+  // Atomic persistence: write a sibling tmp file, then rename over the real
+  // one (rename is atomic within a volume). A crash mid-write leaves the
+  // old config intact instead of a truncated file.
+  const tmp = `${file}.tmp`
+  writeFileSync(tmp, JSON.stringify(cached, null, 2), 'utf8')
+  try {
+    renameSync(tmp, file)
+  } catch {
+    // Windows rename can briefly fail with EPERM/EBUSY (AV scan) — drop the
+    // target and retry; fall back to a non-atomic write as a last resort.
+    try {
+      rmSync(file, { force: true })
+      renameSync(tmp, file)
+    } catch {
+      writeFileSync(file, JSON.stringify(cached, null, 2), 'utf8')
+    }
+  }
   return cached
 }

package/electron/crashGuard.js

@@ -0,0 +1,60 @@
+/**
+ * Crash guard — last-resort observability for the Electron main process.
+ *
+ * Unhandled errors used to vanish (a GUI process has no console), leaving
+ * only "the window didn't come up". Mirror the host half's diagnostics
+ * philosophy (reportLaunchFailure): append one entry per event to
+ * userData/shell-crash.log so a user can attach something actionable to a
+ * bug report.
+ *
+ * The log is capped: past 128 KB the oldest content is dropped, so a
+ * repeating failure can never grow the file without bound.
+ */
+import { app } from 'electron'
+import { appendFileSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const MAX_BYTES = 128 * 1024
+const KEEP_BYTES = 32 * 1024
+
+function crashLogFile() {
+  return join(app.getPath('userData'), 'shell-crash.log')
+}
+
+/** Where the crash log lives (named in docs / bug-report guidance). */
+export function crashLogPath() {
+  return crashLogFile()
+}
+
+function append(entry) {
+  try {
+    const file = crashLogFile()
+    try {
+      if (statSync(file).size > MAX_BYTES) {
+        // Cap: keep only the newest KEEP_BYTES when the log outgrows itself.
+        const tail = readFileSync(file, 'utf8').slice(-KEEP_BYTES)
+        writeFileSync(file, tail, 'utf8')
+      }
+    } catch {
+      // First write (file missing) — nothing to cap.
+    }
+    appendFileSync(file, entry, 'utf8')
+  } catch {
+    // Nowhere left to report to — stay silent rather than crash the guard.
+  }
+}
+
+/**
+ * Install process-level handlers. Errors are logged and swallowed: for a
+ * tray-resident shell, surviving one stray async rejection beats dying on
+ * it — the process-level state after a handled uncaughtException is the
+ * same "best effort" the shell already applies everywhere else.
+ */
+export function setupCrashGuard() {
+  process.on('uncaughtException', (err) => {
+    append(`[${new Date().toISOString()}] uncaughtException: ${err?.stack || err}\n`)
+  })
+  process.on('unhandledRejection', (reason) => {
+    append(`[${new Date().toISOString()}] unhandledRejection: ${reason?.stack || reason}\n`)
+  })
+}

package/electron/main.js

@@ -12,14 +12,19 @@ import { app, BrowserWindow, dialog, nativeImage } from 'electron'
 import { fileURLToPath } from 'node:url'
 import { createMainWindow, reloadWindow } from './window.js'
 import { createTray, refreshTrayMenu } from './tray.js'
-import { loadConfig, saveConfig } from './config.js'
+import { loadConfig, saveConfig, DEFAULT_TARGET_URL } from './config.js'
 import { detect } from './service.js'
 import { setupAutoUpdater } from './update.js'
 import { shortcutSupported, hasDesktopShortcut, createDesktopShortcut, ensureStartMenuShortcut } from './shortcut.js'
 import { APP_USER_MODEL_ID } from './aumid.js'
+import { setupCrashGuard } from './crashGuard.js'
 
 const isMac = process.platform === 'darwin'
 
+// Last-resort error capture (userData/shell-crash.log) — install before
+// anything else so even early startup failures leave a trace.
+setupCrashGuard()
+
 // Windows: pin the AppUserModelId so the taskbar shows our whale icon
 // instead of the generic Electron icon. Plugin mode uses a distinct ID
 // (see aumid.js) so Windows re-reads the icon instead of serving a
@@ -65,15 +70,16 @@ if (!gotLock) {
 
   async function createWindow() {
     const config = loadConfig()
-    const target = config.targetUrl || 'http://127.0.0.1:3080'
+    const target = config.targetUrl || DEFAULT_TARGET_URL
 
     mainWindow = createMainWindow({ target })
     mainWindow.on('closed', () => {
       mainWindow = null
     })
     mainWindow.on('close', (event) => {
-      // Close hides to tray unless we are actually quitting.
-      if (!app.isQuitting && config.closeToTray !== false) {
+      // Close hides to tray unless we are actually quitting. Read the
+      // config fresh so a runtime change to closeToTray takes effect.
+      if (!app.isQuitting && loadConfig().closeToTray !== false) {
         event.preventDefault()
         mainWindow?.hide()
       }
@@ -90,9 +96,11 @@ if (!gotLock) {
    */
   async function bootstrapBackend() {
     const config = loadConfig()
-    const target = config.targetUrl || 'http://127.0.0.1:3080'
+    const target = config.targetUrl || DEFAULT_TARGET_URL
     // Remote targets are the user's own business — never probe local.
-    if (target !== 'http://127.0.0.1:3080') return
+    // Origin comparison (not string equality) tolerates trailing slashes
+    // and an explicitly written default.
+    if (new URL(target).origin !== new URL(DEFAULT_TARGET_URL).origin) return
     await detect()
     // Reflect the post-detect state in the tray menu.
     refreshTrayMenu()
@@ -134,7 +142,7 @@ if (!gotLock) {
       },
       onReload: () => {
         if (mainWindow && !mainWindow.isDestroyed()) {
-          reloadWindow(mainWindow, loadConfig().targetUrl || 'http://127.0.0.1:3080')
+          reloadWindow(mainWindow, loadConfig().targetUrl || DEFAULT_TARGET_URL)
         }
       },
       onQuit: () => {

package/electron/service.js

@@ -11,10 +11,23 @@
  */
 import { spawn } from 'node:child_process'
 import { access } from 'node:fs'
+import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
-import { loadConfig } from './config.js'
+import { loadConfig, DEFAULT_TARGET_URL } from './config.js'
 
-const DEFAULT_PORT = 3080
+// The local backend endpoint — derived from the shared default, never a
+// duplicated literal.
+const LOCAL_URL = DEFAULT_TARGET_URL
+const DEFAULT_PORT = Number(new URL(DEFAULT_TARGET_URL).port) || 80
+
+// Long-lived backend output must not accumulate without bound — keep the
+// tail only (enough for ready-line matching and diagnostics).
+const OUTPUT_CAP = 64 * 1024
+
+function cappedAppend(prev, chunk) {
+  const s = prev + chunk
+  return s.length > OUTPUT_CAP ? s.slice(-OUTPUT_CAP) : s
+}
 
 let child = null
 let currentStatus = 'stopped'
@@ -48,7 +61,7 @@ export function getStatus() {
   return {
     status: currentStatus,
     port: DEFAULT_PORT,
-    url: `http://127.0.0.1:${DEFAULT_PORT}`,
+    url: LOCAL_URL,
     error: lastError,
     pid: child?.pid ?? null,
   }
@@ -57,10 +70,9 @@ export function getStatus() {
 /** Simple HTTP probe — true when something responds on the port. */
 export async function probe(url, timeoutMs = 1500) {
   try {
-    const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(), timeoutMs)
-    const res = await fetch(url, { signal: controller.signal, redirect: 'follow' })
-    clearTimeout(timer)
+    // AbortSignal.timeout is the standard self-cleaning timeout — no manual
+    // controller/timer pair to leak when fetch rejects first.
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' })
     return res.status < 500
   } catch {
     return false
@@ -73,11 +85,10 @@ export async function probe(url, timeoutMs = 1500) {
  * or null when the backend is down.
  */
 export async function detect() {
-  const url = `http://127.0.0.1:${DEFAULT_PORT}`
-  const up = await probe(url)
+  const up = await probe(LOCAL_URL)
   if (up) {
     setStatus('running')
-    return url
+    return LOCAL_URL
   }
   setStatus('stopped')
   return null
@@ -154,13 +165,12 @@ export async function start({ backendPath } = {}) {
       startResolver = null
       // Timeout does not mean failure — the port may already be up while
       // the CLI never printed a parseable URL. Probe before giving up.
-      const url = `http://127.0.0.1:${DEFAULT_PORT}`
-      if (await probe(url, 1500)) {
+      if (await probe(LOCAL_URL, 1500)) {
         setStatus('running')
-        r.resolve(url)
+        r.resolve(LOCAL_URL)
         return
       }
-      child?.kill()
+      terminate(child)
       setStatus('error', 'dsh 后端启动超时（45s）')
       r.reject(new Error(lastError))
     }, 45000)
@@ -178,11 +188,11 @@ export async function start({ backendPath } = {}) {
       }
     }
     child.stdout.on('data', (d) => {
-      stdout += d.toString()
+      stdout = cappedAppend(stdout, d.toString())
       onData()
     })
     child.stderr.on('data', (d) => {
-      stderr += d.toString()
+      stderr = cappedAppend(stderr, d.toString())
       onData()
     })
   })
@@ -191,8 +201,8 @@ export async function start({ backendPath } = {}) {
 /**
  * Stop the backend.
  *
- * - If the backend was spawned by us, kill our child (and force-free the
- *   port — a shell-spawned .cmd can leave orphan node processes behind).
+ * - If the backend was spawned by us, terminate our child (tree kill — a
+ *   shell-spawned .cmd can leave orphan node processes behind).
  * - Otherwise (an external instance, e.g. the user ran `dsh web` themselves)
  *   find the process listening on the port and terminate it, but only when
  *   it looks like a node-based backend, never an unrelated program.
@@ -202,11 +212,7 @@ export async function stop() {
     const proc = child
     child = null
     setStatus('stopped')
-    await new Promise((resolve) => {
-      proc.once('exit', resolve)
-      proc.kill()
-      setTimeout(resolve, 3000)
-    })
+    await terminate(proc)
     await ensurePortFree(DEFAULT_PORT)
     return
   }
@@ -225,6 +231,37 @@ export async function stop() {
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/**
+ * Terminate a spawned backend and wait for it to exit.
+ *
+ * On Windows `proc.kill()` only reaches the direct child — when the command
+ * is a .cmd shim, the node process it launched survives and keeps holding
+ * the port. `taskkill /T` (tree kill) is the recognized fix. POSIX: SIGTERM
+ * first, SIGKILL after a short grace period.
+ */
+async function terminate(proc) {
+  if (!proc || proc.exitCode !== null || proc.signalCode !== null) return
+  const exited = new Promise((resolve) => proc.once('exit', resolve))
+  if (process.platform === 'win32' && proc.pid) {
+    await killProcess(proc.pid)
+  } else {
+    try {
+      proc.kill('SIGTERM')
+    } catch {
+      // already gone
+    }
+  }
+  const done = await Promise.race([exited.then(() => true), sleep(3000).then(() => false)])
+  if (!done && process.platform !== 'win32') {
+    try {
+      proc.kill('SIGKILL')
+    } catch {
+      // already gone
+    }
+    await Promise.race([exited, sleep(1000)])
+  }
+}
+
 /** Wait until nothing answers on the port (or give up after ~6s). */
 async function ensurePortFree(port, tries = 12) {
   const url = `http://127.0.0.1:${port}`
@@ -319,10 +356,28 @@ export async function findDshInFolder(folder) {
   return null
 }
 
+/**
+ * Candidate dsh CLI locations beyond the explicit config path:
+ * the DSH_BACKEND_DIR env var (documented, machine-independent) and the
+ * npm global bin dir. The previous list carried a developer-specific
+ * absolute path — removed in favor of config (backendPath) and env.
+ */
+function fallbackCandidates() {
+  const list = []
+  const envDir = process.env.DSH_BACKEND_DIR
+  if (envDir) list.push(join(envDir, 'dsh.cmd'), join(envDir, 'dsh'))
+  if (process.platform === 'win32') {
+    list.push(join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'npm', 'dsh.cmd'))
+  } else {
+    list.push('/usr/local/bin/dsh', join(homedir(), '.local', 'bin', 'dsh'))
+  }
+  return list
+}
+
 /**
  * Auto-detect the dsh install folder (the folder that contains the dsh
  * CLI), following the same resolution order used to start the backend:
- * PATH → common Windows install locations. Returns the folder path or null.
+ * config → DSH_BACKEND_DIR → PATH → npm global. Returns the folder or null.
  */
 export async function detectInstallFolder() {
   // 1) Explicit backend folder from config.
@@ -332,20 +387,14 @@ export async function detectInstallFolder() {
     if (found) return dirOf(found)
   }
 
-  // 2) `dsh` on PATH → resolve where it actually lives.
+  // 2) Candidates: DSH_BACKEND_DIR env, then npm global bin.
+  for (const c of fallbackCandidates()) {
+    if (await exists(c)) return dirOf(c)
+  }
+
+  // 3) `dsh` on PATH → resolve where it actually lives.
   const onPath = await commandPath('dsh')
   if (onPath) return dirOf(onPath)
-
-  // 3) Common locations.
-  if (process.platform === 'win32') {
-    const candidates = [
-      'D:\\deepseek-harness\\prod\\node_modules\\.bin\\dsh.cmd',
-      `${process.env.USERPROFILE}\\AppData\\Roaming\\npm\\dsh.cmd`,
-    ]
-    for (const c of candidates) {
-      if (await exists(c)) return dirOf(c)
-    }
-  }
   return null
 }
 
@@ -357,23 +406,17 @@ async function resolveDshCommand(backendPath) {
     if (found) return { command: found, args: [] }
   }
 
-  // 2) `dsh` on PATH — resolve to the real file so .cmd/.bat gets the
+  // 2) Candidates: DSH_BACKEND_DIR env, then npm global bin.
+  for (const c of fallbackCandidates()) {
+    if (await exists(c)) return { command: c, args: [] }
+  }
+
+  // 3) `dsh` on PATH — resolve to the real file so .cmd/.bat gets the
   //    shell treatment (a bare `spawn('dsh')` would ENOENT on Windows).
   const onPath = await commandPath('dsh')
   if (onPath) {
     return { command: /\.(cmd|bat)$/i.test(onPath) ? onPath : 'dsh', args: [] }
   }
-
-  // 3) Common locations (dev convenience).
-  if (process.platform === 'win32') {
-    const candidates = [
-      'D:\\deepseek-harness\\prod\\node_modules\\.bin\\dsh.cmd',
-      `${process.env.USERPROFILE}\\AppData\\Roaming\\npm\\dsh.cmd`,
-    ]
-    for (const c of candidates) {
-      if (await exists(c)) return { command: c, args: [] }
-    }
-  }
   return null
 }
 

package/electron/shortcut.js

@@ -1,5 +1,5 @@
 /**
- * Desktop shortcut management (Windows .lnk via WScript.Shell).
+ * Desktop shortcut management (Windows .lnk via Electron's shell API).
  *
  * Used by:
  *  - first-run prompt in main.js ("create a desktop shortcut?")
@@ -12,11 +12,14 @@
  *
  * Pure dev mode (npm run dev from a checkout) has no stable executable,
  * so the feature stays disabled there.
+ *
+ * Electron's built-in shortcut API replaced the earlier hand-rolled
+ * PowerShell + WScript.Shell COM script: fewer moving parts (no spawned
+ * interpreter to hang or quote-escape), and it composes with the
+ * Start-menu shortcut path that already used the same API.
  */
 import { app, shell } from 'electron'
-import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { homedir } from 'node:os'
+import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { APP_USER_MODEL_ID } from './aumid.js'
@@ -45,64 +48,53 @@ export function shortcutSupported() {
   return isWin && (app.isPackaged || pluginArgs().length > 0)
 }
 
-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))
-  })
+/**
+ * The user's real Desktop. app.getPath('desktop') resolves OneDrive
+ * redirection and roaming profile policies — a hardcoded ~/Desktop misses
+ * those and writes the shortcut where the user will never see it.
+ */
+function desktopDir() {
+  try {
+    return app.getPath('desktop')
+  } catch {
+    return join(app.getPath('home'), 'Desktop')
+  }
 }
 
 /** 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)
+export function hasDesktopShortcut() {
+  if (!isWin || !shortcutSupported()) return false
+  try {
+    const target = process.execPath.toLowerCase()
+    for (const entry of readdirSync(desktopDir())) {
+      if (!entry.toLowerCase().endsWith('.lnk')) continue
+      try {
+        // readShortcutLink throws on invalid/non-shortcut files — skip those.
+        const link = shell.readShortcutLink(join(desktopDir(), entry))
+        if (String(link.target).toLowerCase() === target) return true
+      } catch {
+        // unreadable .lnk — not ours
+      }
+    }
+  } catch {
+    // unreadable desktop — treat as "not present"
+  }
+  return false
 }
 
 /** Create (or overwrite) the desktop shortcut for this app. Returns bool. */
-export async function createDesktopShortcut() {
+export function createDesktopShortcut() {
   if (!shortcutSupported()) return false
-  const target = process.execPath
   const args = pluginArgs()
-  const lnk = join(homedir(), 'Desktop', SHORTCUT_NAME)
-  // Plugin mode: point the shortcut at the runtime exe + main.js argument.
-  // WScript needs the path double-quoted inside the Arguments string.
-  const argPart = args.length
-    ? `; $s.Arguments = ${ps(`"${args[0]}"`)}; `
-    : ''
-  // Plugin-mode exe has no custom icon resource — point the shortcut at the
-  // bundled .ico when present (packaged installers use the exe itself).
-  const iconLoc = existsSync(ICON_ICO) ? ICON_ICO : `${target},0`
-  const script =
-    `$ws = New-Object -ComObject WScript.Shell; ` +
-    `$s = $ws.CreateShortcut(${ps(lnk)}); ` +
-    `$s.TargetPath = ${ps(target)}; ` +
-    argPart +
-    `$s.WorkingDirectory = ${ps(dirname(target))}; ` +
-    `$s.IconLocation = ${ps(iconLoc)}; ` +
-    `$s.Save()`
-  const out = await runPs(script)
-  return out !== null
+  const ico = existsSync(ICON_ICO) ? ICON_ICO : undefined
+  // 'overwrite' makes the call idempotent (safe to re-run after updates).
+  return shell.writeShortcutLink(join(desktopDir(), SHORTCUT_NAME), 'overwrite', {
+    target: process.execPath,
+    args: args.length ? args.join(' ') : undefined,
+    icon: ico,
+    iconIndex: 0,
+    appUserModelId: APP_USER_MODEL_ID,
+  })
 }
 
 /**
@@ -115,7 +107,7 @@ export async function createDesktopShortcut() {
 export function ensureStartMenuShortcut() {
   if (!isWin || !shortcutSupported()) return false
   const lnkDir = join(
-    process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'),
+    process.env.APPDATA || join(app.getPath('home'), 'AppData', 'Roaming'),
     'Microsoft', 'Windows', 'Start Menu', 'Programs',
   )
   const lnk = join(lnkDir, SHORTCUT_NAME)