dsh-clean-desktop-shell 0.1.11 → 0.1.13

package/lib/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/lib/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/lib/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')
+  }
+}

package/lib/index.js

@@ -12,7 +12,7 @@ import { spawn } from 'node:child_process'
 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'
+import { ensureRcedit, patchExeIcon } from './icon.js'
 
 // cordis registers the plugin by this name — bundles without an explicit
 // `name` export are silently skipped by the dsh loader.
@@ -21,25 +21,98 @@ export const name = 'dsh-clean-desktop-shell'
 // Disable auto-launch with DSH_SHELL_AUTO_LAUNCH=0.
 const AUTO_LAUNCH = process.env.DSH_SHELL_AUTO_LAUNCH !== '0'
 
+/**
+ * Hard budget for the taskbar-icon step. It runs before the spawn (Windows
+ * locks a running image), so it is on the launch path — but the icon is
+ * cosmetic and must never decide when the window appears. Without a budget a
+ * stalled rcedit fetch held the first launch for up to the fetchFile default
+ * of 600 s; with it, the worst case is 25 s and the usual case is ~0 (the
+ * fetch has already finished behind the Electron runtime download).
+ */
+const ICON_PATCH_DEADLINE_MS = 25000
+
 let launched = false
 
+/**
+ * Let a best-effort step run, but never wait longer than `ms` for it. Whatever
+ * it was doing keeps running in the background.
+ */
+function withDeadline(ctx, promise, ms) {
+  let timer
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      ctx.logger.warn(`[clean-desktop-shell] icon step exceeded ${ms} ms — launching without it`)
+      resolve()
+    }, ms)
+    // Do not keep the host process alive just to fire a warning.
+    timer.unref?.()
+  })
+  const settled = promise.then(() => {}, () => {})
+  return Promise.race([settled, deadline]).finally(() => clearTimeout(timer))
+}
+
 export function apply(ctx) {
   ctx.logger.info('[clean-desktop-shell] mounted (host half)')
   if (!AUTO_LAUNCH) return
-  // The dsh bundle loader calls apply() during early boot, but the cordis
-  // 'ready' event never fires for bundle plugins (dshmarket / agent-teams
-  // use ctx.inject or run inline instead). Launch directly: the shell is a
-  // separate process with its own offline screen + auto-reconnect, so an
-  // early launch is safe — it shows the offline page until 3080 answers.
-  ;(async () => {
-    try {
-      const exe = await ensureRuntime(ctx)
-      await patchExeIcon(ctx, exe).catch(() => {})
-      launchShell(exe, ctx)
-    } catch (err) {
+
+  // Runtime preparation is independent of authentication — start it now, but
+  // defer the Electron spawn until the launch URL is minted below.
+  let runtimeExe = null
+  // Kick the (tiny) rcedit fetch off alongside the (large) Electron runtime so
+  // the two never serialise; patchExeIcon reuses this same memoised promise.
+  void ensureRcedit(ctx)
+  const runtimeReady = ensureRuntime(ctx)
+    .then(async (exe) => {
+      runtimeExe = exe
+      await withDeadline(ctx, patchExeIcon(ctx, exe), ICON_PATCH_DEADLINE_MS)
+    })
+    .catch((err) => {
       reportLaunchFailure(ctx, err)
+    })
+
+  // DSH 0.1.2 BrowserAuth: the shell must not start on bare "/" (401). It
+  // needs this process's launch URL (?token=…), which the Connection service
+  // alone can mint. The service is only reachable from a deferred inject
+  // scope — reading ctx.connection in apply() throws "cannot get property
+  // without inject" — and the URL is a readiness signal: mint it only after
+  // the Loader tree settles, because the port answers 4xx before settlement.
+  // Mirror @deepseek-ai/dsh-web-app's announce pattern.
+  ctx.inject(['connection'], (connectionCtx) => {
+    const launch = () => {
+      if (launched) return
+      // Only injected services are directly reachable in this scope; the
+      // webServer sibling is read through get() (see web-app: it may declare
+      // webServer in its row inject, this host does not).
+      const webServer = connectionCtx.get('webServer')
+      if (!webServer) return
+      try {
+        const webUrl = `http://127.0.0.1:${String(webServer.port)}`
+        // dsh 0.1.2+ mints this process's launch URL through BrowserAuth.
+        // Older versions have no BrowserAuth at all — they serve the web root
+        // unauthenticated — so a missing mint must NOT stop the launch: the
+        // shell just starts with no bootstrap URL, which is exactly the
+        // pre-0.1.2 behaviour.
+        const mint = connectionCtx.connection.authenticatedUrl
+        const launchUrl = typeof mint === 'function' ? mint.call(connectionCtx.connection, webUrl) : null
+        void runtimeReady.then(() => {
+          if (runtimeExe) launchShell(runtimeExe, connectionCtx, launchUrl)
+        })
+      } catch (err) {
+        reportLaunchFailure(connectionCtx, err)
+      }
+    }
+    // This row's own activation can precede a sibling failure. The tree owns
+    // readiness: await the Loader, then re-check that the services still
+    // exist — an early shutdown must not spawn a shell for a dead server.
+    const settled = connectionCtx.get('loader')?.await()
+    if (settled === undefined) launch()
+    else {
+      void settled.then(() => {
+        if (connectionCtx.get('webServer') !== undefined
+          && connectionCtx.get('connection') !== undefined) launch()
+      }, () => {})
     }
-  })()
+  })
 }
 
 /**
@@ -81,11 +154,13 @@ function reportLaunchFailure(ctx, err) {
   }
 }
 
-function launchShell(exe, ctx) {
+function launchShell(exe, ctx, launchUrl) {
   if (launched) return
+  const env = { ...process.env, ELECTRON_RUN_AS_NODE: undefined }
+  if (launchUrl) env.DSH_WEB_LAUNCH_URL = launchUrl
   const child = spawn(exe, [MAIN_JS], {
     cwd: PKG_ROOT,
-    env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined },
+    env,
     stdio: 'ignore',
     windowsHide: false,
   })