jgamboaandClaude
0eb5608873
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>
293 lines
14 KiB
Markdown
293 lines
14 KiB
Markdown
# miniSCP
|
||
|
||
A cross-platform, dual-panel SFTP/local file manager — a small WinSCP-style
|
||
commander built on **Bun**, **Electrobun**, and **Angular**.
|
||
|
||
Each of the two panels independently shows either the local filesystem or a
|
||
remote server over SSH/SFTP, so you can move files **local↔remote**,
|
||
**remote↔remote**, or **local↔local** through one symmetric engine.
|
||
|
||
> **Name & icon are placeholders.** See [Rebranding](#rebranding) — it's a
|
||
> one-file change.
|
||
|
||
## Developer docs
|
||
|
||
Dense reference material lives in [docs/](docs/): [architecture](docs/architecture.md)
|
||
(processes, windows, RPC, every module/service), [build & release](docs/build-and-release.md)
|
||
(Build-n versioning, per-target release pipeline, CI), [platform notes](docs/platform-notes.md)
|
||
(macOS/Windows/Linux matrix, runtime deps + smoke tests), and
|
||
[gotchas](docs/gotchas.md) (known landmines).
|
||
|
||
## Features
|
||
|
||
- Dual-panel commander UI; either panel can be Local or any saved connection.
|
||
- **Session tabs**: each tab is an independent left/right workspace; remote
|
||
sessions stay connected and transfers keep running in background tabs.
|
||
- Per-panel action toolbar with a direction-explicit send button, plus a
|
||
VSCode-style status bar showing live transfer progress (click to expand the
|
||
transfer queue with per-file speed and ETA).
|
||
- **Overwrite confirmation** on name collisions, with a source-vs-destination
|
||
comparison (size, modified date, which is newer) and batch replace-all /
|
||
skip-all.
|
||
- **Settings** (gear, top-right): light / dark / system theme and speed units
|
||
(MB/s or Mbps), persisted across restarts.
|
||
- On macOS the tab bar is fused with the window titlebar; other platforms keep
|
||
a standard titlebar.
|
||
- **Menu-bar (tray) icon**: template icon that adapts to light/dark; click it
|
||
to bring the app to the front.
|
||
- **Edit files** (F4 / toolbar / File menu): a built-in editor works on local
|
||
and remote files directly; or pick an external app (Settings → Editor →
|
||
Custom → Choose…). External edits of remote files download to a temp folder,
|
||
are watched, and every save auto-uploads (visible in the transfer list) until
|
||
the session disconnects. Leftover temp files from a crash are offered for
|
||
cleanup at the next start.
|
||
- Browse, sort (name/size/modified, folders first), keyboard navigation.
|
||
- Create folder / file, rename, delete (recursive), change permissions (chmod).
|
||
- Upload, download, and remote→remote send — files **and** whole folders —
|
||
with a transfer queue, per-job progress, and cancel.
|
||
- Connection manager: saved connections organised into folders, password or
|
||
private-key auth (with passphrase).
|
||
|
||
## Stack
|
||
|
||
| Layer | Choice |
|
||
| ---------- | ------------------------------------------------------------- |
|
||
| Runtime | Bun (main process, all SSH/SFTP + file IO) |
|
||
| 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 |
|
||
| SSH/SFTP | `ssh2` (pure-JS under Bun) |
|
||
|
||
The repo is a Bun workspace: the Electrobun app at the root, the Angular app in
|
||
`ui/`. Shared types and the RPC contract live in `src/shared/` and are imported
|
||
by both sides.
|
||
|
||
```
|
||
src/shared/ types.ts, rpc.ts (wire contract), branding.ts
|
||
src/bun/ Electrobun main process
|
||
fs/ FileSystemProvider + LocalProvider + SftpProvider + registry
|
||
transfers/ engine.ts (queue/stream copy) + walk.ts (recursive helpers)
|
||
store/ connections.json persistence
|
||
ui/src/app/ Angular components + signal services
|
||
```
|
||
|
||
## Prerequisites
|
||
|
||
- [Bun](https://bun.sh) ≥ 1.3 (`bun --version`).
|
||
- macOS: **Xcode Command Line Tools** (for the app build).
|
||
- Linux: **AppIndicator** — the app links it for the tray and will not start
|
||
without it (`ERR_DLOPEN_FAILED`). `libayatana-appindicator` (Arch),
|
||
`libayatana-appindicator3-1` (Debian/Ubuntu),
|
||
`libayatana-appindicator-gtk3` (Fedora), plus system `webkit2gtk`.
|
||
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
|
||
|
||
```bash
|
||
bun install # installs root + ui workspace deps
|
||
```
|
||
|
||
## Develop
|
||
|
||
```bash
|
||
bun run dev
|
||
```
|
||
|
||
This starts the Angular dev server (hot reload for UI code) and launches the
|
||
Electrobun app pointed at it. Edits under `ui/` reload instantly; edits to the
|
||
Bun main process (`src/bun/**`, RPC schema) trigger an app relaunch.
|
||
|
||
## Releases
|
||
|
||
Versioning is Sublime-style: **Build n**, where n is the commit count
|
||
(`git rev-list --count HEAD`), regenerated into the gitignored
|
||
`src/shared/version.gen.ts` by every build script (and `postinstall`).
|
||
|
||
One artifact per invocation, on the matching host — electrobun cannot
|
||
cross-compile (Hutch builds for its own OS and arch):
|
||
|
||
```sh
|
||
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`
|
||
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.
|
||
|
||
## Build a packaged app
|
||
|
||
```bash
|
||
bun run build # ng build (ui/dist) + electrobun build -> build/*/miniSCP*.app
|
||
```
|
||
|
||
The Angular bundle is copied into the app under `views://app`. The macOS icon is
|
||
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://electrobun.dev/electrobun/) for signing,
|
||
notarization, and release hosting).
|
||
|
||
## Rebranding
|
||
|
||
Everything user-facing reads from **[`src/shared/branding.ts`](src/shared/branding.ts)**:
|
||
|
||
```ts
|
||
export const BRANDING = {
|
||
appName: "miniSCP", // window title, bundle name, app-data folder
|
||
identifier: "es.teknes.miniscp",
|
||
legacyNames: [], // previous names; their data dirs migrate on boot
|
||
version: "0.1.0",
|
||
icon: "assets/icon.iconset",
|
||
} as const;
|
||
```
|
||
|
||
To change the icon: edit `assets/logo.svg` (app icon) and
|
||
`assets/tray/tray-glyph.svg` (menu-bar glyph), then run
|
||
`bun scripts/gen-icons.ts` — it regenerates the macOS iconset, `icon.png`, the
|
||
tray template image, and the tray progress frames from the SVGs
|
||
(`@resvg/resvg-js`, dev-only dependency).
|
||
|
||
> Renaming `appName` changes the app-data directory. Add the old name to
|
||
> `legacyNames` and the app moves the previous folder (connections, settings,
|
||
> edit temp files) into place on the next boot.
|
||
|
||
## Where connections are stored
|
||
|
||
Saved connections live in a plain JSON file in the OS app-data directory
|
||
(macOS: `~/Library/Application Support/miniSCP/connections.json`), written with
|
||
`0600` permissions.
|
||
|
||
> ⚠️ **Passwords are stored in plaintext** in this file (a deliberate v1
|
||
> simplicity choice). Anyone who can read the file can read the passwords. If
|
||
> that isn't acceptable for your use, use key-based auth or don't save the
|
||
> password (connect ad-hoc). OS-keychain storage is a natural future addition.
|
||
|
||
## Keyboard shortcuts
|
||
|
||
`Tab` switch panel · `↑`/`↓`/`PgUp`/`PgDn`/`Home`/`End` move cursor ·
|
||
`Space` select · `Enter` open folder · `Backspace` parent ·
|
||
`Ctrl/Cmd+A` select all · `F5` send to other panel · `F2` rename ·
|
||
`F7` new folder · `F8`/`Delete` delete · `Cmd/Ctrl+T` new tab ·
|
||
`Cmd/Ctrl+W` close tab · `Ctrl+Tab` next tab · `Cmd/Ctrl+,` settings ·
|
||
`Cmd/Ctrl+=`/`-`/`0` interface bigger / smaller / 100%.
|
||
|
||
(On Macs, function keys may need `fn` — every action also has a toolbar button.)
|
||
|
||
## Same-file protection
|
||
|
||
Copying a file or folder onto itself would truncate it to zero bytes (the
|
||
destination is opened for writing before the source is read). miniSCP blocks
|
||
this at several layers:
|
||
|
||
- **Same session / same host**: every connection carries a filesystem identity
|
||
(`local`, or `resolvedIP:port` — the hostname is DNS-resolved, so
|
||
`myserver.lan` and its IP compare equal even across two panels/tabs holding
|
||
separate SSH sessions to the same server). Equal identity + equal or nested
|
||
paths ⇒ the transfer is refused before anything is opened.
|
||
- **Hidden aliases** (two *different* addresses that reach the same machine —
|
||
NAT, split DNS): when identities differ but source and destination paths
|
||
collide anyway, a probe file is written through one connection and looked up
|
||
through the other; if it's visible on both, they're the same machine and the
|
||
copy is refused. (SFTP offers no device/inode identity — the mechanism
|
||
`cp`/`rsync` use locally — so probing is the only deterministic test.)
|
||
- The overwrite dialog never offers to "Replace" a file with itself — such
|
||
items are auto-skipped with a notice.
|
||
|
||
**Known residual limitation**: the same filesystem mounted at *different
|
||
paths* on two connections (bind mounts, NFS exported twice, shared container
|
||
volumes) cannot be detected — the paths differ, so no guard or probe triggers.
|
||
Be careful when two panels reach the same data through different mount points.
|
||
|
||
## Portability notes
|
||
|
||
Platform seams are isolated behind `process.platform` / `PLATFORM` branches
|
||
marked with `PORTABILITY:` comments: editor launch (`open` / `cmd /c start` /
|
||
`xdg-open`), app pickers, owner/group lookups, tray images, window chrome,
|
||
shell-integration wording, drive listing, and the connections-file ACL. The
|
||
application menu ([src/bun/menu.ts](src/bun/menu.ts)) is macOS-only for now;
|
||
the in-app UI covers every menu action.
|
||
|
||
Right-click menus are **HTML, on every platform**
|
||
([ui/src/app/core/context-menu.service.ts](ui/src/app/core/context-menu.service.ts)) rather than native —
|
||
electrobun's native context menu is a documented no-op on Linux, and one menu
|
||
implementation beats two that drift. Only reveal / open-with-default / copy-path
|
||
cross to the backend, through the `shellItemAction` RPC.
|
||
|
||
## Windows (beta)
|
||
|
||
Windows 11+ x64 is supported as a **beta** target (win-arm64 deferred). All
|
||
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 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. 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).
|
||
|
||
First-Windows-boot smoke test: drives dropdown lists C:\ etc.; navigate to a
|
||
drive root ('..' disappears); local↔remote transfers; external editor launch
|
||
(`cmd /c start`) and the .exe picker; Show in Explorer / Recycle Bin; tray icon
|
||
renders colored; Permissions absent on local panels; Ctrl+labels in tooltips;
|
||
portable zip runs from any folder.
|
||
|
||
## Linux (beta)
|
||
|
||
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
|
||
its tray icon.
|
||
|
||
- **No native menus at all** upstream (both the app menubar and context menus
|
||
are no-ops). The menubar was already macOS-only and the context menus are now
|
||
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 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. 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).
|
||
|
||
## Known issues
|
||
|
||
- **Rare native crash under load.** A long-running session (multiple remote
|
||
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. 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 AppImage/.deb packages (the release is Electrobun's
|
||
Setup installer).
|