fix(desktop): resolve electronDist dynamically + self-heal blocked installs (supersedes #48081/#48082)

[OutThisLife]

Summary

A consolidated fix for the June desktop-build outage that removes the whole failure class instead of chasing each symptom. Supersedes the static-path approach in #48081 (merged) and the install-step self-heal in #48082 (open), and closes out the community cluster #48003 / #48012 / #48033.

Three distinct faults converged; this closes all three:

#	Failure mode	Status
1	The specified electronDist does not exist (path mismatch)	fixed permanently (dynamic resolution)
2	ERR_DLOPEN_FAILED … extract-zip-win32-x64-msvc (native binding)	already fixed by the exact 40.10.2 pin on main
3	npm ci aborts on a blocked Electron download	fixed (install-step self-heal)

Root cause (the part #48081 left open — "Gap B")

build.electronDist was a static relative path in apps/desktop/package.json, but npm workspace hoisting is not deterministic — depending on the npm version and what else is installed, npm nests the workspace-only electron devDep under apps/desktop/node_modules/electron or hoists it to the repo root. A static path matches only one layout, so a clean install intermittently fails with The specified electronDist does not exist.

#48081 re-pointed the path at the nested layout (correct today), but electron-builder reads electronDist statically — so a future hoist change silently breaks it again, caught only by a CI invariant, never self-corrected. #48082 fixes the blocked-download case but doesn't change when the path resolves.

Research — why this is the durable fix, and how others solve it

I traced the original intent and surveyed how real electron + npm-workspace monorepos handle this before settling on the approach:

• Why electronDist exists here at all (Fix macOS desktop packaging when Electron binary is missing #38673 / commit f3b32e9f5): it was added because electron-builder 26.8.x can stage an Electron.app missing its Contents/MacOS/Electron binary when it re-unpacks Electron from its own cache, failing the electron → Hermes rename with ENOENT. Pointing electronDist at the already-unpacked dist makes electron-builder reuse it and dodge that bug. So removing electronDist outright would reintroduce the macOS failure — the fix has to keep dist-reuse while making the path correct. (We're on electron-builder@^26.8.1, the affected line.)
• electron-builder's own monorepo guidance (electron-userland/electron-builder#7103): for npm/yarn workspaces, (1) pin electron to an exact version (no ^/~) — done, 40.10.2; and (2) don't hardcode the path — let electron-builder resolve Electron via node module resolution. v26 explicitly added workspace support that checks both the project dir and the app dir (#9219).
• electronDist accepts a path string OR a resolver function in v26 (electron.build/configuration), and -c.electronDist=<path> is a documented CLI override that merges onto the package.json build config (electron.build/cli; the Arch packaging guide uses exactly electron-builder ... -c.electronDist=$electronDist -c.electronVersion=$electronVer).

Conclusion: resolve the path the way Node's runtime does and hand it to electron-builder as a merge override — hoist-proof, keeps dist-reuse, no config-file migration.

Fix

1. Dynamic, hoist-proof electronDist (scripts/run-electron-builder.cjs)

require.resolve("electron/package.json") walks node_modules from the desktop project upward and finds Electron wherever npm actually put it. The path can never drift out of sync with the install layout again, on any OS / npm version.

• dist present → pass -c.electronDist=<abs>/dist so electron-builder reuses the unpacked runtime (keeps the Fix macOS desktop packaging when Electron binary is missing #38673 fast path that dodges the 26.8.x missing-binary re-unpack bug).
• dist absent → omit electronDist; electron-builder fetches Electron itself via @electron/get, honoring electronVersion + ELECTRON_MIRROR.

package.json: the builder script runs the wrapper and the static build.electronDist is removed (the resolver owns it).

2. Install-step self-heal (main.py / install.sh / install.ps1)

electron's install.js does process.exit(1) on a blocked/throttled binary download, failing the whole npm ci before pack — which made the pack-time mirror self-heal dead code on a blocked network (#47266/#47917/#48021). npm runs postinstall scripts last, so when the download is the casualty the electron package is staged and only its dist/ is missing. On that failure we repopulate the dist (canonical, then npmmirror.com) and continue to the build instead of aborting; we hard-fail only when electron never staged at all (a genuine dependency error). The pack-time fallback now also retries under ELECTRON_MIRROR even when the pre-fetch is blocked, because the wrapper lets electron-builder download Electron itself via the mirror.

Validation

• tests/test_desktop_electron_pin.py + tests/hermes_cli/test_gui_command.py: 46 passed (new contracts: no static electronDist to drift, builder routes through the resolver, resolver uses require.resolve + injects -c.electronDist; install-failure self-heals and continues; genuine install failure still hard-fails; pack retries under the mirror when pre-fetch is blocked).
• Wrapper functionally verified against fake electron / electron-builder packages: injects -c.electronDist=<abs> when the dist exists, omits it when absent.
• install.sh desktop tests (symlink-stomp, node-prefix, browser, unmerged-index, no-initial-commit): 17 passed. node --check, bash -n, py_compile clean.
• Not yet run: a full local npm ci && npm run pack on each OS (heavy ~200MB download). The change to electron-builder's resolved path is behaviorally equivalent to fix(desktop): resolve electronDist to the actual electron install location #48081 in the common (nested) case — only the path source changes (static → require.resolve).

Credits

Salvages/supersedes the overlapping community work in #48003 (@sitkarev), #48012 (@omegazheng), #48033 (@james47kjv), and #48082 (@AIalliAI) — authorship preserved via co-author trailers. Closes #48084, #48019, #48021; relates to #47917, #46785, #47266.

[github-actions]

🔎 Lint report: hermes/desktop-electron-superfix vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10926 on HEAD, 10926 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 5723 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[alt-glitch]

Related: #48081 (merged static-path fix), #48082 (open install self-heal), #48003 (canonical community workspace-resolution PR + #48012/#48028/#48033/#48050 twins), #47917/#48084/#48019/#48021 (bug reports), #46785/#47266 (installer misdiagnosis).

This PR takes a different mechanism than the cluster: instead of a static electronDist path, it resolves Electron via require.resolve("electron/package.json") (hoist-proof) in a new scripts/run-electron-builder.cjs wrapper, and removes the static build.electronDist. Treated as related-not-duplicate (different mechanism, supersedes rather than re-implements). Maintainer to choose between the dynamic-resolver approach here and the static-path cluster.

[OutThisLife]

Follow-up hardening pushed in 0d97727 to close the remaining #46785-style misdiagnosis risk:\n\n- Recovery path is now gated to the specific Electron-missing-dist shape (package.json + install.js staged and dist missing/corrupt).\n- Unrelated npm install failures now hard-fail immediately (no Electron narrative).\n- Cache purge/retry on pack failure now runs only when Electron dist is actually missing/corrupt; unrelated tsc/vite failures are no longer retried under Electron-specific messaging.\n- Added regression test coverage for the hard-fail path when Electron dist already exists.\n\nAlso ran an end-to-end mac validation in this worktree:\n- npm ci (repo root): success\n- cd apps/desktop && npm run pack: success (darwin arm64 packaged, custom unpacked Electron dist used).