JokinandClaude
6c05e39ce1
`bun run start` printed nothing and exited 0 without ever opening a window. electrobun's prebuilt CLI is a Bun single-file executable whose payload is appended after the linker ad-hoc signed it, so `codesign -v` reports "code or signature have been modified" and the macOS kernel SIGKILLs it at exec. The failure was invisible because bin/electrobun.cjs spawns the real binary and forwards `process.exit(code || 0)` — a signal death has `code === null`. Confirmed upstream, not local corruption: a fresh download from the GitHub release hashes identical to the shipped copy and fails the same check. Both the darwin-arm64 and darwin-x64 CLI tarballs are affected. scripts/fix-electrobun-cli.ts re-seals the binary with `codesign --force --sign -`. It runs from postinstall AND ahead of every electrobun invocation, because the wrapper downloads the CLI lazily on first use rather than at install time — postinstall alone would no-op on a fresh checkout. When the binary is missing it provokes that download first, so a clean tree self-heals. It also fixes .cache/electrobun, which the wrapper restores bin/ from, and release.ts re-signs the Rosetta x64 CLI on download and on cache reuse. Idempotent (~0.3s when already valid) and a no-op off macOS. Verified from a deleted-binary state: `bun run start` downloads, re-signs and launches. Co-Authored-By: Claude <noreply@anthropic.com>
146 lines
9.0 KiB
Markdown
146 lines
9.0 KiB
Markdown
# Build & release
|
||
|
||
## Versioning — "Build n"
|
||
|
||
Sublime-style: the version IS the commit count. `scripts/gen-version.ts` runs
|
||
`git rev-list --count HEAD` + `git rev-parse --short HEAD` and writes the
|
||
**gitignored** `src/shared/version.gen.ts` (`BUILD = {number, commit, date,
|
||
electrobun}`). It is regenerated by `postinstall` and at the start of every
|
||
`dev`/`build`/`start`/`release` script; committing it would bump the count it
|
||
records, hence gitignored. Fresh checkouts fail `tsc` until `bun install` has
|
||
run once (postinstall creates the file). `BRANDING.version` stays
|
||
semver-shaped (`0.1.<n>`) for electrobun's config/updater; `BRANDING.buildLabel`
|
||
("Build n") is what humans see (About box, options popover).
|
||
|
||
## Dev loop
|
||
|
||
- `bun run dev` — gen-version → scripts/dev.ts: starts `ng serve` (HMR) and
|
||
`electrobun dev --watch`, with `DEV_SERVER_URL` pointing the webviews at the
|
||
dev server (only honored on the dev channel and only if the server answers).
|
||
- `bun run build` — gen-version → Angular build → `electrobun build`
|
||
(**dev channel** — fine for boot checks, NOT a release).
|
||
- `scripts/node-version-shim.ts` (preloaded via `bunfig.toml`, root AND ui/)
|
||
fakes a Node version the Angular CLI accepts under Bun. Both preloads are
|
||
load-bearing.
|
||
- `scripts/fix-electrobun-cli.ts` re-signs electrobun's prebuilt CLI binary,
|
||
whose upstream ad-hoc signature is invalid — macOS SIGKILLs it and the app
|
||
silently never launches, with exit code 0 (see [gotchas.md](gotchas.md)). It
|
||
runs from `postinstall` **and** at the start of `dev`/`start`/`build`/
|
||
`release`, because the CLI is downloaded lazily on first use rather than at
|
||
install time; when the binary is missing it provokes that download first, so
|
||
a fresh checkout self-heals. Equally load-bearing — removing it means
|
||
`bun run start` does nothing at all.
|
||
|
||
## Release builds
|
||
|
||
`bun scripts/release.ts [--target mac-arm64|mac-x64|win-x64]` (default: host).
|
||
Steps: gen-version → fix-electrobun-cli → gen-icons → Angular build →
|
||
`electrobun build --env=stable` → copy/rename artifacts into
|
||
`release/<target>/miniSCP-Build<n>-<target>.*`.
|
||
|
||
Facts the script encodes:
|
||
|
||
- **`--env=stable` is mandatory for releases** — the CLI defaults to the dev
|
||
channel (different app name `miniSCP-dev`, no distributable artifacts).
|
||
- **No OS cross-compile.** The CLI builds for its host (its `targets` config
|
||
field is unread in 1.18.1); packaging needs host tools (codesign/hdiutil on
|
||
macOS, rcedit/PowerShell on Windows). Hence one script run per artifact, on
|
||
the matching machine; `win-x64` on a non-Windows host errors out.
|
||
- **mac-x64 from the arm64 Mac (Rosetta)**: the script downloads electrobun's
|
||
x64 CLI binary once (`electrobun-cli-darwin-x64.tar.gz` from the GitHub
|
||
release matching the installed version, cached at
|
||
`~/.cache/miniscp/electrobun-cli-x64-<ver>/`) and runs it directly —
|
||
Rosetta translates it, the CLI sees `process.arch === "x64"`, downloads the
|
||
`dist-macos-x64` core into the electrobun package dir on first use, and
|
||
packages a genuine x64 app. Note: Bun's `fetch`→`Bun.write` streaming hung
|
||
on the GitHub redirect chain; the script uses `curl -fsSL` deliberately.
|
||
- **Both CLI binaries need re-signing.** The x64 CLI fetched for the Rosetta
|
||
path carries the same broken upstream signature as the arm64 one, so
|
||
`x64Cli()` re-signs it after download *and* on cache reuse; the native path
|
||
is covered by the `fix-electrobun-cli.ts` step up front.
|
||
- **Core binary downloads**: the installed npm package ships mac-arm64
|
||
binaries only; other `dist-<os>-<arch>` cores are fetched from
|
||
`github.com/blackboardsh/electrobun/releases` at build time — network to
|
||
GitHub is a build-time requirement on every fresh machine/runner.
|
||
- **Artifact shapes** (stable channel, in `artifacts/`): macOS →
|
||
`stable-macos-<arch>-miniSCP.dmg` + `.app.tar.zst` + `update.json`
|
||
(updater feed); Windows → `stable-win-x64-miniSCP-Setup.zip`
|
||
(self-extracting installer → `%LOCALAPPDATA%`) plus the script's own
|
||
**portable zip** made from the assembled app folder under
|
||
`build/stable-win-x64/` (layout to confirm on the first real Windows build —
|
||
the step warns instead of failing).
|
||
- The script filters artifacts by app name, so stale artifacts from older
|
||
brandings don't get collected.
|
||
|
||
## CI (Gitea Actions)
|
||
|
||
`.gitea/workflows/release.yml` — tag-triggered (`build-*`), macos + windows
|
||
runner matrix, each running the same release script; inert until act_runners
|
||
with those labels are registered. Needs `fetch-depth: 0` (the build number is
|
||
the commit count). Runner prereqs are commented in the workflow file.
|
||
|
||
## Download host (`site/` + Caddy)
|
||
|
||
`site/` is a self-contained landing page **and** download host, served by Caddy on an
|
||
internal box (plain HTTP `:80`, no domain/TLS). Deploys to `/srv/miniscp/`.
|
||
|
||
- `site/index.html` — pure static, no JS, tinygrad-minimal. Download buttons link to **fixed
|
||
stable filenames** (`/dl/stable-macos-arm64-miniSCP.dmg`, …) so the page never changes per
|
||
release. Logo/screenshot `<img>` slots are commented in, images live in `site/assets/`.
|
||
- `site/Caddyfile` — one flat `/dl/*` folder with `file_server browse` + range requests, and
|
||
per-type `Cache-Control`: `*.patch` immutable (unique hashed names), `*update.json` `no-cache`
|
||
(updater must see new versions), installers (`*.dmg *.zip *.tar.zst`) `max-age=300` (stable
|
||
names overwritten each release). Landing page has **no** SPA fallback → unknown paths 404.
|
||
Path matcher gotcha: use suffix globs like `*update.json`, not `*/*update.json`.
|
||
- **One flat folder, no per-build dirs** — this layout IS electrobun's `artifacts/` feed, so it
|
||
doubles as the (future) updater `baseUrl`. Publishing = drop this machine's `artifacts/stable-*`
|
||
into `/dl/`; installers overwrite in place, `.patch` files accumulate (never delete them, or
|
||
older installs lose their incremental-update trail). **Tradeoff:** only the latest full
|
||
installer is downloadable; old full versions are overwritten.
|
||
- `site/deploy.sh` — run per build machine after `scripts/release.ts`; copies `artifacts/stable-*`
|
||
and renames the build-numbered win portable zip to the stable `stable-win-x64-miniSCP-portable.zip`.
|
||
`MINISCP_DL_DIR` overrides the target (stage locally, then rsync to the server).
|
||
- `release.baseUrl = https://miniscp.com/dl` is set in `electrobun.config.ts`; `miniscp.com` is
|
||
fronted by an external proxy for TLS (Caddy itself stays on `:80` behind it). The value is baked
|
||
into `version.json` at build time, so only builds made after it was added check for updates.
|
||
With `generatePatch` (default true), release builds now need **build-time network to
|
||
`miniscp.com/dl`** so electrobun can fetch the currently-published version to diff a `.patch`
|
||
(the first build after enabling it has nothing to diff and just ships the full artifacts).
|
||
|
||
## Auto-updater (app side)
|
||
|
||
Wired on top of the download host above. See the "Auto-updater" section in
|
||
[architecture.md](architecture.md) for the runtime flow.
|
||
|
||
- **Backend** ([src/bun/index.ts](../src/bun/index.ts)): `Updater.checkForUpdate()` runs ~5s after launch and
|
||
every 6h; on `updateAvailable` it pushes `rpc.send.updateStatus({phase:"available",…})`.
|
||
`Updater.onStatusChange` streams `download-progress` (0–100) → `updateStatus{downloading}`.
|
||
`checkForUpdate` self-guards the `dev` channel, so `bun run dev` never shows the pill.
|
||
- **RPC** ([src/shared/rpc.ts](../src/shared/rpc.ts)): requests `checkForUpdate` / `downloadUpdate` /
|
||
`applyUpdate` (handlers in [rpc-handlers.ts](../src/bun/rpc-handlers.ts) call the electrobun `Updater`);
|
||
push message `updateStatus`.
|
||
- **UI**: `UpdaterService` ([ui/src/app/updater.service.ts](../ui/src/app/updater.service.ts)) holds signals
|
||
(`state`/`version`/`progress`); the tab-bar "update pill" ([tab-bar.ts](../ui/src/app/tab-bar/tab-bar.ts))
|
||
is one accent (`bg-primary`) control that announces → fills as a progress bar while downloading →
|
||
"Restart to apply". `state` is `available → downloading → ready` (ready derived from the
|
||
`downloadUpdate` response). App-menu "Check for Updates…" ([menu.ts](../src/bun/menu.ts)) routes a
|
||
`check-for-updates` menu action into `UpdaterService.check()`.
|
||
- **Unsigned is fine:** `applyUpdate()` strips the macOS quarantine xattr before relaunch, so the
|
||
swapped bundle isn't Gatekeeper-blocked.
|
||
|
||
## Icons
|
||
|
||
`scripts/gen-icons.ts` (resvg, dev-time): renders `assets/logo.svg` into the
|
||
macOS iconset + `icon.png`, a multi-size `assets/icon.ico` (Windows installer/
|
||
taskbar, wired via `electrobun.config.ts win.icon`), the macOS tray template
|
||
PNG from `assets/tray/tray-glyph.svg`, and a small colored Windows tray PNG.
|
||
Rerun after touching either SVG; outputs are committed (build inputs).
|
||
|
||
## electrobun config notes
|
||
|
||
`electrobun.config.ts`: app identity comes from `BRANDING`; `build.bun.external`
|
||
must keep `["cpu-features", "*.node"]` (ssh2's optional native accelerators —
|
||
bundling them breaks the build; runtime falls back to pure JS);
|
||
`build.copy` ships the Angular dist and tray assets into `views://`;
|
||
`bundleCEF: false` everywhere (system WebKit / WebView2).
|