dsh-clean-desktop-shell 0.1.6 → 0.1.8

package/lib/runtime.js

@@ -23,8 +23,17 @@ import {
   rmSync,
   symlinkSync,
 } from 'node:fs'
-import { join } from 'node:path'
-import { PKG_ROOT, EXE_NAME, ARCH, PLATFORM, runtimeRoot } from './common.js'
+import { basename, join } from 'node:path'
+import {
+  PKG_ROOT,
+  EXE_RELPATH,
+  EXE_TOP,
+  ARCH,
+  PLATFORM,
+  isWin,
+  isMac,
+  runtimeRoot,
+} from './common.js'
 
 function electronVersion() {
   try {
@@ -49,18 +58,19 @@ export async function ensureRuntime(ctx) {
   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)
+  const exe = join(dir, EXE_RELPATH)
 
   // 1) Already provisioned for this version?
   if (existsSync(exe)) {
     cleanupOldVersions(root, dir)
+    if (!isWin) await ensureExecutable(ctx, exe)
     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)
+    const srcExe = join(localSrc, 'dist', EXE_RELPATH)
     if (existsSync(srcExe) && provisionLocalDist(localSrc, dir)) {
       ctx.logger.info(`[clean-desktop-shell] reused electron runtime from ${localSrc}`)
     }
@@ -73,43 +83,130 @@ export async function ensureRuntime(ctx) {
   }
 
   if (!existsSync(exe)) {
+    // Name the exact path we expected. Without it a user on an untested
+    // platform has nothing to report back (this failure used to be silent).
     throw new Error(
-      'electron runtime provisioning failed — check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
+      `electron runtime provisioning failed — expected binary at ${exe} ` +
+        `(platform=${PLATFORM} arch=${ARCH}, layout differs per platform); ` +
+        'check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
     )
   }
   cleanupOldVersions(root, dir)
+  if (!isWin) await ensureExecutable(ctx, exe)
   ctx.logger.info(`[clean-desktop-shell] electron runtime ${version} ready at ${dir}`)
   return exe
 }
 
+/**
+ * Zip extraction does not reliably restore the executable bit — bsdtar
+ * (Windows tar.exe, macOS /usr/bin/tar) in particular drops it — and a
+ * non-executable binary fails later with a bare EACCES on spawn. Guarantee
+ * it instead of trusting the extractor.
+ */
+function ensureExecutable(ctx, target) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('chmod', ['+x', target], { stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        ctx.logger.warn(`[clean-desktop-shell] chmod +x failed (exit ${code}) on ${target}`)
+      }
+      resolve(code === 0)
+    })
+  })
+}
+
 async function downloadRuntime(ctx, version, root, dir) {
   const tmpZip = join(root, `.electron-${version}.zip.tmp`)
   rmSync(tmpZip, { force: true })
   const urls = await runtimeUrls(version)
+  const innerName = zipName(version).replace(/\.zip$/, '')
+
   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 })
-      }
+    if (!(await fetchFile(url, tmpZip))) {
+      // Failed download — drop the partial file so a later run starts clean.
+      rmSync(tmpZip, { force: true })
+      continue
     }
-    // Failed download — drop the partial file so a later run starts clean.
+
+    // Extract into a scratch dir, never into the shared runtime root: a
+    // half-extracted zip there would be indistinguishable from a real
+    // runtime, and the sibling electron-v* dirs must not be disturbed.
+    const scratch = join(root, `.extract-${version}-${Date.now()}`)
+    const ok = await extractZip(ctx, tmpZip, scratch)
     rmSync(tmpZip, { force: true })
+    if (!ok) {
+      ctx.logger.warn(`[clean-desktop-shell] no extractor succeeded for ${url}`)
+      rmSync(scratch, { recursive: true, force: true })
+      continue
+    }
+
+    // Both archive layouts exist in the wild: some Electron zips wrap
+    // everything in a dir named after the zip, others (notably darwin, whose
+    // payload is Electron.app/) unpack flat into the destination. Detect
+    // rather than assume — the old code assumed the wrapper and silently
+    // produced nothing on macOS.
+    const payload = findPayload(scratch, join(scratch, innerName))
+    if (!payload) {
+      ctx.logger.warn(
+        `[clean-desktop-shell] unexpected archive layout: no ${EXE_TOP} under ${scratch}`,
+      )
+      rmSync(scratch, { recursive: true, force: true })
+      continue
+    }
+
+    movePayloadInto(dir, payload)
+    rmSync(scratch, { recursive: true, force: true })
+    if (isMac) await clearQuarantine(ctx, join(dir, EXE_TOP))
+    return
   }
   throw new Error('electron download failed from all sources')
 }
 
+/** The dir that directly holds the electron payload right after extraction. */
+function findPayload(scratch, wrapper) {
+  if (existsSync(join(wrapper, EXE_TOP))) return wrapper
+  if (existsSync(join(scratch, EXE_TOP))) return scratch
+  return null
+}
+
+function movePayloadInto(dir, payload) {
+  rmSync(dir, { recursive: true, force: true })
+  renameSync(payload, dir)
+}
+
+/**
+ * macOS: a bundle carrying com.apple.quarantine is refused by Gatekeeper with
+ * the infamous "已损坏，无法打开" dialog. We download with curl (which does
+ * not set the attribute), but archive members themselves can carry it, so
+ * clear it once right after extraction rather than debugging it per user.
+ */
+function clearQuarantine(ctx, target) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('xattr', ['-cr', target], { windowsHide: true, stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => {
+      ctx.logger.info(
+        code === 0
+          ? `[clean-desktop-shell] cleared extended attributes on ${target}`
+          : `[clean-desktop-shell] xattr cleanup skipped (exit ${code})`,
+      )
+      resolve(code === 0)
+    })
+  })
+}
+
 /**
  * Pick the download source by racing a HEAD probe against each candidate
  * (direct connection, 3s each). The fastest reachable source goes first —
@@ -162,21 +259,81 @@ function fetchFile(url, dest) {
   })
 }
 
-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}`))))
+/**
+ * Extract a zip using whatever the platform actually provides.
+ *
+ * The archives are ordinary zips, but the readers differ:
+ *   - Windows: bsdtar ships as tar.exe and reads zip; Expand-Archive is the
+ *     fallback for hardened images where tar is unavailable.
+ *   - macOS:   ditto -xk is Apple's own extractor and preserves the symlinks
+ *              inside Electron.app; unzip next; bsdtar last.
+ *   - Linux:   unzip, then tar.
+ *
+ * Success is decided by the caller (findPayload), not by the exit code — a
+ * zip can unpack "successfully" into a layout nobody expects.
+ */
+function extractZip(ctx, zipPath, dest) {
+  const strategies = isWin
+    ? [
+        { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        {
+          cmd: 'powershell',
+          args: [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `Expand-Archive -LiteralPath '${zipPath.replace(/'/g, "''")}' -DestinationPath '${dest.replace(/'/g, "''")}' -Force`,
+          ],
+        },
+      ]
+    : isMac
+      ? [
+          { cmd: 'ditto', args: ['-xk', zipPath, dest] },
+          { cmd: 'unzip', args: ['-q', '-o', zipPath, '-d', dest] },
+          { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        ]
+      : [
+          { cmd: 'unzip', args: ['-q', '-o', zipPath, '-d', dest] },
+          { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        ]
+
+  return (async () => {
+    mkdirSync(dest, { recursive: true })
+    for (const s of strategies) {
+      const ok = await runExtractor(s.cmd, s.args)
+      if (ok) {
+        ctx.logger.info(`[clean-desktop-shell] extracted with ${s.cmd}`)
+        return true
+      }
+      ctx.logger.warn(`[clean-desktop-shell] extractor unavailable or failed: ${s.cmd}`)
+    }
+    return false
+  })()
+}
+
+function runExtractor(cmd, args) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(cmd, args, { windowsHide: true, stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
   })
 }
 
-/** Remove version dirs older than the current one (dead weight). */
+/**
+ * Drop version dirs older than the current one (dead weight), plus any
+ * scratch dir a crashed extraction left behind.
+ */
 function cleanupOldVersions(root, currentDir) {
   try {
     for (const entry of readdirSync(root)) {
-      if (!entry.startsWith('electron-v')) continue
+      const isStaleRuntime = entry.startsWith('electron-v')
+      const isScratch = entry.startsWith('.extract-') || entry.startsWith('.electron-')
+      if (!isStaleRuntime && !isScratch) continue
       const full = join(root, entry)
       if (full === currentDir) continue
       rmSync(full, { recursive: true, force: true })
@@ -187,11 +344,15 @@ function cleanupOldVersions(root, currentDir) {
 }
 
 /**
- * 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.
+ * Provision a local electron package's dist/ as the version dir itself, so
+ * the layout matches a downloaded runtime: <dir>/<EXE_RELPATH> at the
+ * version-dir root (on macOS that is <dir>/Electron.app/Contents/MacOS/Electron).
+ *
+ * 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.
+ * macOS/Linux: a symlink to dist/ would work too, but a bare .app reached
+ * through a symlink is a common source of Gatekeeper/entitlement surprises,
+ * so always copy there.
  */
 function provisionLocalDist(srcPkg, destDir) {
   if (process.platform === 'win32') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-clean-desktop-shell",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Clean desktop shell for DeepSeek Harness (DSH) as a DSH plugin — wraps your web profile in a native window, tray-managed backend, offline auto-reconnect, zero visual changes. DSH 插件形态的纯净桌面壳：复用现有 web profile，托盘管理后端，零视觉改造。",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
+    "CONTRIBUTORS.md",
     "LICENSE",
     "version.txt"
   ],
@@ -32,7 +33,7 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "check": "node --check lib/index.js",
+    "check": "node --check lib/index.js && node scripts/selftest-runtime.mjs",
     "dev": "electron electron/main.js",
     "icons": "node scripts/gen-icons.mjs",
     "pack": "electron-builder --win nsis",
@@ -97,7 +98,8 @@
       "target": [
         "dmg"
       ],
-      "category": "public.app-category.developer-tools"
+      "category": "public.app-category.developer-tools",
+      "icon": "build/icon.png"
     },
     "nsis": {
       "oneClick": true,

package/scripts/selftest-runtime.mjs

@@ -0,0 +1,90 @@
+/**
+ * Self-check for the Electron runtime path logic.
+ *
+ * Guards the macOS launch bug: Electron's three archives have three
+ * different layouts, and only darwin ships an app bundle with no top-level
+ * binary. This fakes each platform and each archive layout, then asserts
+ * join(versionDir, EXE_RELPATH) resolves to a real file — the exact
+ * condition ensureRuntime() checks before spawning the shell.
+ *
+ * Run: node scripts/selftest-runtime.mjs
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, sep } from 'node:path'
+import { tmpdir } from 'node:os'
+import { pathToFileURL } from 'node:url'
+
+// Layouts as Electron actually ships them (authoritative mapping lives in
+// the `electron` package's own install.js, which writes path.txt):
+//   win32  → <dir>/electron.exe
+//   linux  → <dir>/electron
+//   darwin → <dir>/Electron.app/Contents/MacOS/Electron
+const LAYOUTS = {
+  win32: ['electron.exe', 'resources/placeholder'],
+  linux: ['electron', 'resources/placeholder'],
+  darwin: [
+    'Electron.app/Contents/MacOS/Electron',
+    'Electron.app/Contents/Info.plist',
+  ],
+}
+
+let failures = 0
+
+function check(label, cond) {
+  console.log(`  ${cond ? 'ok  ' : 'FAIL'} ${label}`)
+  if (!cond) failures++
+}
+
+/** Materialise an extracted-archive tree under dir. */
+function buildLayout(dir, entries) {
+  for (const rel of entries) {
+    const full = join(dir, ...rel.split('/').map((s) => s.split('\\').join(sep)))
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, 'binary')
+  }
+}
+
+async function forPlatform(platform) {
+  Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+  // Cache-bust so the module re-evaluates its platform-derived constants.
+  const { EXE_RELPATH, EXE_TOP } = await import(
+    `${pathToFileURL(join(process.cwd(), 'lib', 'common.js')).href}?p=${platform}`
+  )
+
+  const root = mkdtempSync(join(tmpdir(), `dsh-shell-${platform}-`))
+  const dir = join(root, 'electron-v33.4.11')
+  console.log(`\n[${platform}]`)
+  try {
+    buildLayout(dir, LAYOUTS[platform])
+    const exe = join(dir, EXE_RELPATH)
+
+    check(`EXE_TOP = ${EXE_TOP}`, typeof EXE_TOP === 'string' && EXE_TOP.length > 0)
+    check(`binary resolves: ${EXE_RELPATH}`, existsSync(exe))
+    check('resolved path lives inside the version dir', exe.startsWith(dir))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+// Regression guard: prove the pre-fix constant was broken on darwin, so this
+// test would actually have caught the bug rather than just passing forever.
+async function regression() {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-shell-legacy-'))
+  const dir = join(root, 'electron-v33.4.11')
+  console.log('\n[regression: pre-fix darwin behaviour]')
+  try {
+    buildLayout(dir, LAYOUTS.darwin)
+    const legacyExe = 'electron' // what EXE_NAME used to be on every non-Windows platform
+    check(`legacy join(dir, 'electron') is absent — the bug`, !existsSync(join(dir, legacyExe)))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+await regression()
+for (const p of ['win32', 'linux', 'darwin']) {
+  await forPlatform(p)
+}
+
+console.log(`\n${failures === 0 ? 'PASS' : `FAIL (${failures} check(s))`}`)
+process.exit(failures === 0 ? 0 : 1)

package/src/host/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/src/host/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], {