jgamboa/miniSCP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Migrate to Electrobun 2.0.2 (Hutch)

Browse Source 
Electrobun 2.x replaces the vendored CLI with Hutch: the npm package is now a
bootstrap whose exports are a throwing stub, and the SDK is projected into
.hutch/devkit. The app stays on the Bun main process — `mainProcess: "bun"` is
load-bearing, since the 2.x default (Cottontail) ignores build.bun and with it
the ssh2 externals — and the bundle now ships the pinned Bun 1.4.0.

- electrobun 2.0.2 as an exact devDependency. `electrobun prepare` takes the
  old CLI re-sign step's slot in postinstall and every dev/build/start/release
  script: tsc (root tsconfig extends the devkit's) and the Angular build
  (electrobun/view mapped into the devkit) resolve the SDK there.
- Imports move to electrobun/main. The CLI re-sign script and the v1 "three"
  type shim are gone (Hutch's binaries are validly signed).
- UI: Electroview's bunSocket is hostSocket; noImplicitReturns is off because
  the devkit's raw-TS browser SDK compiles inside the UI program.
- Updater.applyUpdate() now consults before-quit, so the transfers/unsaved
  guard's "Quit Anyway" re-runs the apply instead of quitting without it.
- 2.x applies trafficLightOffset from macOS's default button position (1.18.1
  clamped it inside the titlebar); {12, 4} centres the lights in the header.
- Releases: mac-x64 dropped (2.x publishes no macOS x64 core, so no Rosetta
  path). artifacts/ is emptied before each build and published verbatim.
  Installers lost the stable- prefix (the update feed kept it), so release.ts,
  deploy.sh and the site links follow. Linux ships Electrobun's Setup
  installer instead of the portable tarball and its miniSCP.sh wrapper.
- Docs cover all of the above, plus re-checks against 2.0.2: still no native
  modal windows; window close is now cancellable through will-close.

Verified: tsc, build:ui, a stable mac-arm64 release (dmg + the v1-compatible
stable-macos-arm64 feed) and dev launches (RPC, Settings window, traffic
lights). Windows/Linux builds and the v1 -> 2.x Windows update bridge still
need their first run on native machines.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
jgamboa
2026-10-05 11:08:03 +02:00
co-authored by Claude
parent 9bd237d89c
commit 0eb5608873
30 changed files with 431 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+29 -26
View File
@@ -53,7 +53,7 @@ Dense reference material lives in [docs/](docs/): [architecture](docs/architectu
| Layer | Choice |
| ---------- | ------------------------------------------------------------- |
| Runtime | Bun (main process, all SSH/SFTP + file IO) |
| Desktop | Electrobun 1.18 (native webview, typed RPC bridge) |
| Desktop | Electrobun 2.0 via Hutch (native webview, typed RPC bridge) |
| Frontend | Angular 22 (standalone, signals, zoneless) in `ui/` |
| Styling | Tailwind CSS v4, Oxide-derived tokens (no component library) |
| Icons | @ng-icons/tdesign-icons |
@@ -83,6 +83,10 @@ ui/src/app/ Angular components + signal services
Details and diagnostics in [platform notes](docs/platform-notes.md).
- No Node install required — a preload shim (`scripts/node-version-shim.ts`)
satisfies the Angular CLI's Node version check while running under Bun.
- Network on the first `bun install`: Electrobun 2.x's npm package is a
bootstrap that downloads its build tool (Hutch), the Electrobun core and the
pinned Bun runtime into `~/.hutch` (~200 MB), and projects the SDK into the
gitignored `.hutch/devkit/`.
## Setup
@@ -107,22 +111,19 @@ Versioning is Sublime-style: **Build n**, where n is the commit count
`src/shared/version.gen.ts` by every build script (and `postinstall`).
One artifact per invocation, on the matching host — electrobun cannot
cross-compile between OSes:
cross-compile (Hutch builds for its own OS and arch):
```sh
bun run release -- --target mac-arm64 # on the Mac (native)
bun run release -- --target mac-x64 # on the same arm64 Mac, via Rosetta 2
bun run release -- --target mac-arm64 # on an Apple Silicon Mac
bun run release -- --target win-x64 # on a Windows 11 x64 machine
bun run release -- --target linux-x64 # on a Linux x64 machine
```
Artifacts land in `release/<target>/miniSCP-Build<n>-<target>.*` — a `.dmg`
per mac arch; on Windows a `-Setup.zip` installer **and** a `-portable.zip`
(unzip anywhere and run); on Linux a portable `.tar.gz` (unpack and run
`miniSCP.sh`, which sets the NVIDIA workaround then execs `bin/launcher`).
The mac-x64 build fetches electrobun's x64 CLI once
into `~/.cache/miniscp/` and runs it under Rosetta so the whole pipeline
believes it is on an Intel Mac. CI: `.gitea/workflows/release.yml` runs the
on the Mac; on Windows a `-Setup.zip` installer **and** a `-portable.zip`
(unzip anywhere and run); on Linux Electrobun's `-Setup.tar.gz` installer.
There is no Intel Mac build: Electrobun 2.x publishes no macOS x64 core.
CI: `.gitea/workflows/release.yml` runs the
same script on a macos + windows runner matrix once act_runners are
registered; trigger by pushing a `build-<n>` tag.
@@ -137,7 +138,7 @@ compiled from `assets/icon.iconset` into `AppIcon.icns` automatically.
For a distributable (optimized, with auto-update channel) build, use
`bunx electrobun build --env=stable` (see the
[Electrobun docs](https://framework.blackboard.sh/electrobun/) for signing,
[Electrobun docs](https://electrobun.dev/electrobun/) for signing,
notarization, and release hosting).
## Rebranding
@@ -233,11 +234,12 @@ electrobun APIs the app uses are implemented on Windows; known issues are
upstream:
- **HiDPI blur** ([electrobun#324](https://github.com/blackboardsh/electrobun/issues/324)):
WebView2 renders at 1x on scaled displays until upstream adds DPI awareness.
WebView2 rendered at 1x on scaled displays on Electrobun 1.18; 2.x ships
per-monitor DPI setup — to re-check on the first 2.x Windows build.
- **Notifications** use legacy balloon style, not Windows toast.
- **Unsigned binaries**: both the Setup.exe installer and the portable exe
trigger SmartScreen/Mark-of-the-Web warnings on first run. No Start Menu
entry or uninstaller (installer unpacks to `%LOCALAPPDATA%`).
trigger SmartScreen/Mark-of-the-Web warnings on first run. The installer
unpacks to `%LOCALAPPDATA%` and, since Electrobun 2.x, ships an uninstaller.
- `connections.json` is protected with an `icacls` current-user ACL instead of
POSIX 0600 (which is meaningless on Windows).
@@ -249,7 +251,8 @@ portable zip runs from any folder.
## Linux (beta)
Linux x64 is supported as a **beta** target and builds a portable tarball.
Linux x64 is supported as a **beta** target and ships Electrobun's own
installer (`-Setup.tar.gz`).
One hard requirement: the AppIndicator library listed under
[Prerequisites](#prerequisites) — electrobun links it for the tray, so without
it the app aborts at startup with `ERR_DLOPEN_FAILED` rather than merely losing
@@ -260,12 +263,12 @@ its tray icon.
HTML, so nothing is missing in practice.
- **Tray visibility** depends on the desktop: KDE, XFCE, MATE and Cinnamon show
it; GNOME 3.26+ needs the AppIndicator extension. The app works either way.
- **Unsigned and unpackaged**: no AppImage, `.deb`, desktop entry or icon
installation — unpack the tarball and run `miniSCP.sh`.
- **Unsigned**, and no AppImage or `.deb` — unpack the `-Setup.tar.gz` and run
its `installer`.
- **NVIDIA GPUs** need `WEBKIT_DISABLE_DMABUF_RENDERER=1` or the window renders
black. Every launch path (dev scripts and the packaged `miniSCP.sh` wrapper)
sets it automatically when an NVIDIA driver is detected — see
[gotchas](docs/gotchas.md#linux) if you add a new way to launch the app.
black. The dev scripts set it automatically when an NVIDIA driver is
detected; an installed build needs it set by hand (e.g. in its desktop
entry) — see [gotchas](docs/gotchas.md#linux).
Full dependency table, diagnostics and the first-boot smoke test:
[platform notes](docs/platform-notes.md).
@@ -273,17 +276,17 @@ Full dependency table, diagnostics and the first-boot smoke test:
## Known issues
- **Rare native crash under load.** A long-running session (multiple remote
connections, extended uptime) can hit a Bun panic — a segfault inside Bun
connections, extended uptime) could hit a Bun panic — a segfault inside Bun
1.3.13's FFI thread-safe callbacks executing Electrobun's native→worker
bridge (`FFI_Callback_threadsafe_call` → `web_worker.spin` in the decoded
crash report). This is an upstream Bun × Electrobun bug, not app code; a
restart recovers cleanly and in-flight work isn't corrupted. Expected to
resolve when Electrobun bumps its pinned Bun (currently 1.3.13; 1.3.14+
available). Bun's own crash reporter link is printed to the console on panic.
restart recovers cleanly and in-flight work isn't corrupted. Electrobun 2.0.2
pins Bun 1.4.0, which may have fixed it — not yet confirmed under load. Bun's
own crash reporter link is printed to the console on panic.
## Not in v1
Drag-and-drop, file preview/edit, transfer resume, symlink following
(symlinks are listed but skipped by transfers), OS keychain, tab persistence
across restarts, Linux desktop integration (AppImage/.deb/.desktop entry —
the release is a portable tarball).
across restarts, Linux AppImage/.deb packages (the release is Electrobun's
Setup installer).