miniSCP/docs/build-and-release.md

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.

Release builds

bun scripts/release.ts [--target mac-arm64|mac-x64|win-x64] (default: host). Steps: gen-version → 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.
• 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.

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).