dsh-clean-desktop-shell 0.1.11 → 0.1.13

package/scripts/selftest-runtime.mjs

@@ -1,90 +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)
+/**
+ * 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/client/client.js

@@ -1,11 +1,21 @@
 /**
  * dsh-clean-desktop-shell — client half (web browser bundle).
  *
- * The shell is a standalone Electron window; it injects nothing into the
- * dsh web UI. This client module exists only to satisfy the client-modules
- * loader contract — a bundle's client entry must register itself via
- * `window.__ModuleLoader__.load({ id, factory })`, otherwise dsh reports
- * "loaded without registering … via __ModuleLoader__.load".
+ * Bridges the page's DSH client-runtime connection lifecycle into the
+ * Electron shell so HTTP health alone can never hide a terminal disconnect
+ * (e.g. the backend restarted under the page: HTTP answers again while the
+ * page's WebSocket generation is dead).
+ *
+ *  - ctx.connection.state ('connected' | 'connecting' | 'disconnected') is
+ *    forwarded to the main process (shell:client-connection → preload
+ *    shellAPI.connectionReport);
+ *  - main-process reconnect requests (shell:client-reconnect →
+ *    shellAPI.onReconnectRequest) call ctx.connection.reconnect() —
+ *    recovery through the app's own reconnect loop, never a reload.
+ *
+ * The supported baseline provides ctx.connection.state / reconnect();
+ * missing APIs fail activation loudly instead of degrading. A plain browser
+ * (no shellAPI — no Electron shell) is the only silent case.
  */
 window.__ModuleLoader__.load({
   id: 'dsh-clean-desktop-shell',
@@ -13,7 +23,32 @@ window.__ModuleLoader__.load({
     var module = { exports: {} };
     var exports = module.exports;
     Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-    exports.apply = () => {};
+    exports.inject = ['connection'];
+    exports.apply = function (ctx) {
+      var api = window.shellAPI;
+      if (!api) return;
+      var connection = ctx.connection;
+      var latest = null;
+      var notify = function () {
+        var state = connection.state.getSnapshot();
+        if (state === latest) return;
+        latest = state;
+        if (state === 'connected' || state === 'connecting' || state === 'disconnected') {
+          api.connectionReport(state);
+        }
+      };
+      var unsubscribe = connection.state.subscribe(notify);
+      notify(); // report whatever the runtime already is — a lost initial disconnect must not be hidden
+      var unregisterRequest = api.onReconnectRequest(function () {
+        connection.reconnect();
+      });
+      ctx.effect(function () {
+        return function () {
+          unsubscribe();
+          unregisterRequest();
+        };
+      });
+    };
     return module.exports;
   },
 });

package/src/host/common.js

@@ -1,74 +1,74 @@
-/**
- * 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 { spawn } from 'node:child_process'
-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 isMac = process.platform === 'darwin'
-export const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
-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(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')
-}
-
-/**
- * Download a file to disk via curl — shared by runtime provisioning and
- * icon patching. Chosen over native fetch because undici (Node's fetch)
- * ignores HTTP(S)_PROXY env vars unless a proxy dispatcher is wired in,
- * while curl honors them out of the box (users behind Clash/v2ray rely on
- * that). --max-time keeps a stalled proxy from hanging forever; --retry
- * rides out transient failures.
- */
-export function fetchFile(url, dest, timeoutSec = 600) {
-  return new Promise((resolve) => {
-    const child = spawn(
-      'curl',
-      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', String(timeoutSec), '-o', dest, url],
-      { windowsHide: true, stdio: 'ignore' },
-    )
-    child.on('error', () => resolve(false))
-    child.on('exit', (code) => resolve(code === 0))
-  })
-}
+/**
+ * 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 { spawn } from 'node:child_process'
+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 isMac = process.platform === 'darwin'
+export const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
+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(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')
+}
+
+/**
+ * Download a file to disk via curl — shared by runtime provisioning and
+ * icon patching. Chosen over native fetch because undici (Node's fetch)
+ * ignores HTTP(S)_PROXY env vars unless a proxy dispatcher is wired in,
+ * while curl honors them out of the box (users behind Clash/v2ray rely on
+ * that). --max-time keeps a stalled proxy from hanging forever; --retry
+ * rides out transient failures.
+ */
+export function fetchFile(url, dest, timeoutSec = 600) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      'curl',
+      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', String(timeoutSec), '-o', dest, url],
+      { windowsHide: true, stdio: 'ignore' },
+    )
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+}

package/src/host/icon.js

@@ -1,51 +1,85 @@
-/**
- * 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, fetchFile } 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')
-  }
-}
+/**
+ * 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, fetchFile } from './common.js'
+
+const RCEDIT_NAME = 'rcedit-x64.exe'
+const RCEDIT_URL = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
+
+/**
+ * rcedit is a ~1.3 MB self-contained exe, and its download sits on the launch
+ * path (Windows locks a running image, so the patch has to happen before the
+ * exe is spawned). fetchFile's default budget — 600 s — is sized for the
+ * ~100 MB Electron runtime, not for this: behind a stalled proxy it could keep
+ * the window off screen for ten minutes. Cap it well below that; a miss only
+ * costs the default icon.
+ */
+const RCEDIT_TIMEOUT_SEC = 20
+
+let rceditPromise = null
+
+/**
+ * Fetch (once) the cached rcedit binary next to the runtimes. Memoised so the
+ * host half can start this alongside the Electron runtime download and have
+ * the icon step reuse the same fetch instead of serialising behind it.
+ *
+ * Never rejects: every failure mode just means "no rcedit, default icon".
+ */
+export function ensureRcedit(ctx) {
+  if (!rceditPromise) {
+    rceditPromise = (async () => {
+      try {
+        const rcedit = join(runtimeRoot(), RCEDIT_NAME)
+        if (existsSync(rcedit)) return rcedit
+        ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
+        if (await fetchFile(RCEDIT_URL, rcedit, RCEDIT_TIMEOUT_SEC)) return rcedit
+        ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
+      } catch (err) {
+        ctx.logger.warn(`[clean-desktop-shell] rcedit unavailable (${err?.message ?? err}) — taskbar icon stays default`)
+      }
+      // Not memoised as a failure: a later launch deserves a fresh attempt.
+      rceditPromise = null
+      return null
+    })()
+  }
+  return rceditPromise
+}
+
+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
+
+  const rcedit = await ensureRcedit(ctx)
+  if (!rcedit) 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')
+  }
+}