[CSSFrancis]

The de-shell half of directelectron/de_ground_crew#410: shipping an app as an installer, online or offline. What SpyDE does today moves into the shell, so Ground Crew and Autopilot can ship the same way.

What's in it

pythonEnv: extras, GPU, offline (main/pythonEnv.ts, main/config.ts)

• ShellConfig.pythonExtras are always installed. gpuExtras are installed only when nvidia-smi finds a device. EnsureOptions.gpu or <APPID>_GPU=0|1 overrides the probe.
• Without this, a packaged GC would install CPU-only, because CuPy sits behind its gpu extra and the sync never passed --extra.
• The lock stamp includes the extras. With no extras it stays the bare hash, so existing installs don't re-sync.
• Offline wheelhouse. A wheelhouse is a folder with wheelhouse.json, every locked wheel and a python-build-standalone mirror. The install runs:
  1. uv python install from the file:// mirror;
  2. uv venv;
  3. uv export --frozen;
  4. uv pip install --offline --no-index --require-hashes.
• A frozen uv sync --offline --find-links can't do this: uv looks for registry-locked wheels only in its cache. uv venv also refuses the mirror under UV_OFFLINE, which is why installing the interpreter is a separate step.
• A probed GPU whose extras the wheelhouse lacks falls back to a CPU install and stamps +gpu=unavailable. Without that stamp, an air-gapped GPU machine would retry online, and fail, on every launch. A GPU the user explicitly requested still fails if its extras are missing.
• Managed interpreters now go to <userData>/python instead of %APPDATA%\uv\python, so nothing is left behind on uninstall.

First-run, updater and report UI: one call each (main/envSetup*.ts, main/shellIpc*.ts, preload, renderer)

• runEnvSetup(win, opts) streams throttled env_setup messages. On failure it waits for the user (Retry, Install from a folder…, Quit) instead of leaving a dead window.
• registerUpdaterIpc() and registerProblemReportIpc() register the IPC channels.
• The preload bridge gains updater, report and envSetup, and exports a ShellBridge type.
• EnvSetupOverlay, UpdateCard, UpdateDialog and ReportProblemDialog come from SpyDE, with every string a prop.

Packaging (de_shell/js/packaging/, reached as electron/shell/packaging/)

• python -m de_shell.js link <electronDir> [--soft], plus shell-link.mjs. These replace the copy all three apps carry, which is identical in each.
• bundle-python.mjs stages the <resources>/python payload. It is configured by flags or a deShell block in electron/package.json.
• build-wheelhouse.mjs (new) builds the offline wheelhouse. It evaluates markers for the target platform, not the build host.
• installer.nsh:
  • It tree-kills the app and its sidecar, limited to this app's own userData. SpyDE's version swept any app's python-env.
  • On uninstall it offers to remove the managed environment. The default is No, and silent runs and updates always answer No.
• electron-builder.base.yml is a shared base for an app's builder config to extends.
• .github/workflows/electron-release.yml is a reusable workflow (workflow_call) taken from SpyDE's release pipeline. It also attaches the Windows wheelhouse zip and signs with Azure Trusted Signing when the secrets are present.

The README has a new Shipping an app section.

Testing

• npm run typecheck is clean.
• npm run test:unit: 171 pass.
• uv run pytest: 127 pass, including 10 new tests for link.
• End-to-end, network blocked. I bundled a tiny app with bundle-python.mjs, built GPU and CPU wheelhouses with build-wheelhouse.mjs, then called resolvePythonEnv from Node:
  • GPU wheelhouse: installs, and a relaunch skips the sync.
  • CPU wheelhouse on a GPU machine: falls back to CPU, and a relaunch doesn't retry even with the wheelhouse gone.
  • Explicit GPU with a CPU wheelhouse: fails clearly.
  • Wheelhouse in userData/wheelhouse: found automatically.
  • No wheelhouse: fails cleanly.
  • The interpreter lands under userData/python.

Not yet exercised:

• installer.nsh has never been through makensis.
• The release workflow has never run.
• bundle-python hasn't been run with MinGit or with a multi-package workspace.
• The new React components typecheck but haven't been rendered.

The Ground Crew PR that adopts this will be the first real installer build.