feat(electrobun): Ship — 0.1.0, macOS-only guard, docs, package-test CI, release pipeline (PR5)

[goosewobbler]

PR5 — Ship (stack: feat/electrobun-ship → feat/electrobun-service → main)

Final PR in the @wdio/electrobun-service stack. The service ships pre-1.0 (0.1.0), macOS-only — see #316 and the "Framework gaps" for the upstream CEF catch-22.

Done

• Version → 0.1.0-next.0 (both packages) — releases as 0.1.0; 0.x because upstream blocks Linux/Windows/multiremote/multi-window/deeplink, 1.0 reserved for full parity.
• macOS-only CEF runtime guard — SevereServiceError in launcher.onPrepare native mode on Linux/Windows, framed around the CEF renderer, pointing to macOS / browser mode / Electrobun: support non-CEF (native-renderer) apps to fill the Linux/Windows gaps #317. Browser mode unaffected. (+ unit tests)
• Package-test CI (macOS-only) — _ci-build-electrobun-package-app.reusable.yml (Bun/CEF, symlink-preserving tar), the electrobun arm in _ci-package.reusable.yml, ci.yml build + package jobs + ci-status, detect-changes, test:package:electrobun. Plus the fixture test harness (2-staggered-window backend, wdio.conf.ts, smoke spec, tsconfig.wdio.json) — PR3 had stubbed only a build script.
• scripts/test-package.ts — electrobun threaded (CDP arm) + renamed the stale both service option → all (now excludes electrobun; flattened the service-detect ternary).
• Release pipeline — electrobun scope in release.yml + _release.reusable.yml (CDP target set, no Rust/GTK) + releasekit.config.json (skip fixtures, scope:electrobun). Also fixed the pre-existing dioxus gap in the same file.
• Docs — service README rewritten (0.1.0/macOS-only/limitations/Electrobun: support non-CEF (native-renderer) apps to fill the Linux/Windows gaps #317); root README Experimental Support section; AGENTS/ROADMAP/architecture/package-structure/e2e-testing/CONTRIBUTING.
• Greptile feat: @wdio/electrobun-service — Electrobun desktop testing support #314 ×4 — Error-mock stack symmetry, writeRemoteDebuggingPort JSDoc, syncWebDriverWindow handle restore, drop needless async.

Notes

• ReleaseKit generates release notes + CHANGELOG; no hand-authored docs/release-notes/ file.
• The recurring E2E - Electron/Dioxus [Windows] CI reds are known-flaky and unrelated (re-run clears them).

[greptile-apps]

Greptile Summary

This is the final PR in the @wdio/electrobun-service stack, shipping version 0.1.0 as macOS-only. It adds the CEF platform guard, package-test CI infrastructure, release pipeline wiring, and a set of fixes from the previous review round.

• macOS guard — cefNativeModeMacOnly throws a SevereServiceError in launcher.onPrepare for native mode on Linux/Windows; browser mode is explicitly unaffected; unit tests cover both platforms and the cross-mode interaction.
• Package-test CI — new _ci-build-electrobun-package-app.reusable.yml builds the CEF fixture as a symlink-preserving tarball; _ci-package.reusable.yml gains the electrobun arm (download → extract → pack → --skip-build test); ci.yml adds the two new macOS-ARM jobs and wires them into ci-status; test-package.ts renames both → all and adds the full electrobun service branch.
• Bug fixes — syncWebDriverWindow now restores the caller's original window handle on the no-match path; mock.ts adds stack symmetry; connection.ts drops the needless async/unhandled-promise pattern.

Confidence Score: 5/5

Safe to merge — all changed paths are well-tested, the platform guard and window-handle restore are correct, and the CI wiring follows the established patterns in the repo.

The logic changes are small and well-scoped: the macOS guard is a fail-fast throw correctly positioned after the browser-mode early return; the syncWebDriverWindow restore is a targeted fix with a corresponding mock added to the test; the mock.ts and connection.ts changes are cosmetic/symmetry fixes. The CI additions follow the existing Dioxus/Tauri patterns exactly. No existing behaviour is regressed.

fixtures/package-tests/electrobun-app/wdio.conf.ts uses globSync from node:fs which requires Node 22+, while the service itself advertises Node 18/20 support.

Important Files Changed

Filename	Overview
packages/electrobun-service/src/launcher.ts	Adds macOS-only CEF runtime guard in onPrepare for native mode; correctly placed after the browser-mode early-return so browser mode is unaffected; throws the new cefNativeModeMacOnly error on Linux/Windows.
packages/electrobun-service/src/errors.ts	Adds cefNativeModeMacOnly factory function returning SevereServiceError; message includes platform name, browser-mode escape hatch, and #317 follow-up link.
packages/electrobun-service/src/service.ts	Captures the session's original window handle before the syncWebDriverWindow probe loop and restores it on the no-match path, preventing the session from being stranded on the last probed handle.
packages/electrobun-service/src/mock.ts	Adds stack to the serialised __wdioError object so mockRejectedValue errors arrive with the same shape as errors captured through the read-call-data path.
packages/electrobun-service/test/launcher.spec.ts	Adds a setPlatform helper to stub process.platform per-test (defaulting to darwin), and two new test cases covering the macOS-only guard on Linux and Windows; a browser-mode Linux test is also added.
fixtures/package-tests/electrobun-app/wdio.conf.ts	New WDIO config for the package-install smoke fixture; uses globSync from node:fs (Node 22+) to locate the built .app bundle; mirrors the e2e config pattern.
.github/workflows/_ci-build-electrobun-package-app.reusable.yml	New reusable workflow that builds the Electrobun package-test fixture on macOS with Bun/CEF and uploads the result as a symlink-preserving tarball to avoid .app framework symlink loss.
scripts/test-package.ts	Renames both → all, adds the electrobun service arm (build/pack/install/detect), excludes electrobun-* fixtures from the all run, and flattens the service-detection ternary to a prefix-lookup array.
.github/workflows/_ci-package.reusable.yml	Adds the electrobun arm: downloads the tarball artifact, extracts it with symlink-preservation, packs the service + CDP bridge, and runs the package test with --skip-build; both → all rename propagated consistently.
releasekit.config.json	Adds electrobun scope mapping (@wdio/electrobun-*) and pre-existing dioxus fixtures/scopes that were missing; also adds electrobun and dioxus example/e2e-app names to the skip list.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[launcher.onPrepare] --> B{browser mode?}
    B -- yes --> C[coerce browserName → chrome\nreturn early — no platform check]
    B -- no\nnative mode --> D{process.platform === darwin?}
    D -- no\nLinux / Windows --> E[throw cefNativeModeMacOnly\nSevereServiceError — fast fail]
    D -- yes\nmacOS --> F[resolveElectrobunApp + verifyCefRenderer\nper-capability]
    F --> G[onWorkerStart: clone bundle\npin CDP port → spawn app]
    G --> H[onWorkerEnd: stop app]

    subgraph CI Package Test Pipeline
        I[detect-changes: run_electrobun?] -- true --> J[build job\nDownload JS artifacts]
        J --> K[build-electrobun-package-app-macos-arm\nBun + CEF build → tar upload]
        K --> L[package-electrobun-macos-arm\nDownload tar → extract → pack service → test:package:electrobun --skip-build]
    end

Loading

_{Reviews (6): Last reviewed commit: "test(electrobun): bump e2e specFileRetri..." | Re-trigger Greptile}