Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(console): release a signed Intel macOS build (CHOO-2195) (#249)

Louis Amaudruz52e13b06512f
diff --git a/.github/workflows/switch-console-release.yml b/.github/workflows/switch-console-release.yml
index 4fe5fd08a..2ea46b73d 100644
--- a/.github/workflows/switch-console-release.yml
+++ b/.github/workflows/switch-console-release.yml
@@ -4,10 +4,17 @@ name: Switch Console release
# repo, so anyone can install it without building from source. The repo is public,
# so the release assets are too — no token, no ACL.
#
-# macOS (arm64) is signed + notarized. Linux (x64 and arm64) builds AppImage, deb
-# and rpm, unsigned — each arch on a runner of that arch. Windows (x64) builds nsis
-# and msi, also unsigned — there is no Authenticode identity for this app, so
-# SmartScreen warns on first run (CHOO-1468).
+# macOS (arm64 and x64) is signed + notarized. Linux (x64 and arm64) builds
+# AppImage, deb and rpm, unsigned. Every macOS and Linux arch builds on a runner of
+# that arch. Windows (x64) builds nsis and msi, also unsigned — there is no
+# Authenticode identity for this app, so SmartScreen warns on first run
+# (CHOO-1468).
+#
+# The two macOS jobs do NOT upload a channel manifest. electron-builder gives Linux
+# a per-arch channel file but macOS none, so both write `latest-mac.yml` and one
+# would overwrite the other, leaving that architecture with no update feed and no
+# error to show for it. `merge-mac-manifest` combines them into the single manifest
+# electron-updater expects, listing both architectures (CHOO-2195).
#
# Trigger by pushing a tag like `switch-console-v1.1.34` (the version after
# `switch-console-v` MUST match apps/switch-console-desktop/package.json `version`).
@@ -66,9 +73,9 @@ jobs:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
version="${GITHUB_REF_NAME#switch-console-v}"
- notes="Switch Console desktop app $version — macOS arm64 and Linux x64 + arm64.
+ notes="Switch Console desktop app $version — macOS Apple silicon + Intel, and Linux x64 + arm64.
- **macOS (arm64):** download the .dmg, open it, drag Switch Console to Applications. Signed and notarized with SandboxAQ's Developer ID — it opens without a Gatekeeper bypass.
+ **macOS:** download the .dmg for your Mac — \`switch-console-arm64.dmg\` for Apple silicon (M1 and later), \`switch-console-x64.dmg\` for Intel. Not sure which you have? Apple menu → About This Mac. Open it and drag Switch Console to Applications. Both are signed and notarized with SandboxAQ's Developer ID — they open without a Gatekeeper bypass, and both receive in-app updates.
**Linux (x64 and arm64):** match your \`dpkg --print-architecture\`. Download the .AppImage (\`chmod +x\` then run), the .deb (\`sudo apt install ./<file>.deb\`) or the .rpm (\`sudo dnf install ./<file>.rpm\`). Linux builds are unsigned."
gh release create "$GITHUB_REF_NAME" \
@@ -78,8 +85,8 @@ jobs:
--notes "$notes"
build-macos:
- name: Build & release (macOS arm64)
- runs-on: macos-14
+ name: Build & release (macOS ${{ matrix.arch }})
+ runs-on: ${{ matrix.runner }}
# The Apple Developer ID signing secrets live in the `release` environment
# (required reviewers + branch policy), so a run must be approved and can
# only come from main or a tag — a workflow_dispatch from an arbitrary
@@ -89,10 +96,29 @@ jobs:
# than run. Restricted to main / tags so a feature-branch dispatch is skipped.
needs: create-release
if: ${{ !cancelled() && needs.create-release.result != 'failure' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main') }}
+ strategy:
+ # One arch must not take the other down with it. A half-built pair still
+ # cannot ship: merge-mac-manifest needs both manifests, and publish-release
+ # needs what it produces.
+ fail-fast: false
+ matrix:
+ include:
+ - arch: arm64
+ runner: macos-14
+ - arch: x64
+ # A native Intel runner rather than a flag on the Apple silicon job.
+ # `npmRebuild` is off, so the native modules baked into the package are
+ # the ones `pnpm rebuild` produced on this machine; cross-building
+ # would emit an x64 package carrying arm64 `.node` files, which
+ # installs, launches, and dies on the first database or terminal call.
+ # `macos-13` was retired in December 2025 — `macos-15-intel` is the
+ # x86_64 image, and GitHub retires x86_64 macOS entirely in 2027.
+ runner: macos-15-intel
# Surface the cert/key secrets through env so step-level `if:` can gate on
# them — the `secrets` context is not allowed in `if:` expressions.
env:
APPLE_API_KEY_P8: ${{ secrets.APPLE_API_KEY_P8 }}
+ HAS_DEVELOPER_ID: ${{ secrets.APPLE_CSC_LINK != '' && 'true' || 'false' }}
steps:
- name: Checkout
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
@@ -142,7 +168,7 @@ jobs:
printf '%s' "$APPLE_API_KEY_P8" > "$RUNNER_TEMP/appstore/AuthKey.p8"
echo "APPLE_API_KEY=$RUNNER_TEMP/appstore/AuthKey.p8" >> "$GITHUB_ENV"
- - name: Package (mac arm64, no publish)
+ - name: Package (mac ${{ matrix.arch }}, no publish)
working-directory: console/apps/switch-console-desktop
env:
# Developer ID signing: when the cert secret is set, electron-builder
@@ -154,7 +180,84 @@ jobs:
CSC_IDENTITY_AUTO_DISCOVERY: ${{ secrets.APPLE_CSC_LINK != '' && 'true' || 'false' }}
APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
- run: pnpm exec electron-builder --mac --publish never --config electron-builder.config.ts
+ run: pnpm exec electron-builder --mac --${{ matrix.arch }} --publish never --config electron-builder.config.ts
+
+ - name: Verify the package is really ${{ matrix.arch }}
+ # The flag says which arch was asked for; these binaries say which was
+ # produced. A package built for the wrong arch installs and launches and
+ # then dies on the first wrong-arch `.node`, so check rather than trust.
+ working-directory: console/apps/switch-console-desktop
+ run: |
+ case "${{ matrix.arch }}" in
+ arm64) expected=arm64 ;;
+ x64) expected=x86_64 ;;
+ *) echo "::error::unhandled arch '${{ matrix.arch }}'"; exit 1 ;;
+ esac
+ apps=()
+ while IFS= read -r found; do
+ apps+=("$found")
+ done < <(find release -maxdepth 2 -type d -name '*.app')
+ if [ "${#apps[@]}" -ne 1 ]; then
+ # One target arch means one bundle. More than one means the config
+ # started building both again, and checking an arbitrary bundle would
+ # make this assertion a coin flip on the wrong one.
+ echo "::error::expected exactly one .app under release/, found ${#apps[@]}"
+ printf '%s\n' "${apps[@]}"
+ exit 1
+ fi
+ app="${apps[0]}"
+ binaries=("$app/Contents/MacOS/$(basename "$app" .app)")
+ while IFS= read -r module; do
+ binaries+=("$module")
+ done < <(find "$app" -type f -name '*.node')
+ if [ "${#binaries[@]}" -lt 2 ]; then
+ # asarUnpack is what leaves the native modules on disk to inspect. If
+ # they stop appearing, this check has quietly stopped checking.
+ echo "::error::found no unpacked .node under $app — cannot verify native module arch"
+ exit 1
+ fi
+ failed=""
+ for binary in "${binaries[@]}"; do
+ archs="$(lipo -archs "$binary" 2>/dev/null || echo "unreadable")"
+ case " $archs " in
+ *" $expected "*) echo "ok $archs $binary" ;;
+ *) echo "::error::$binary is '$archs', expected $expected"; failed=1 ;;
+ esac
+ done
+ [ -z "$failed" ]
+
+ - name: Verify Gatekeeper accepts the app
+ # Only meaningful with a real Developer ID: without one the build is
+ # ad-hoc signed, which Gatekeeper rejects by design. An Intel .dmg that
+ # trips Gatekeeper is worse than no Intel .dmg — it looks shipped and
+ # fails in the user's hands — so the release build asserts it here.
+ if: ${{ env.HAS_DEVELOPER_ID == 'true' }}
+ working-directory: console/apps/switch-console-desktop
+ run: |
+ apps=()
+ while IFS= read -r found; do
+ apps+=("$found")
+ done < <(find release -maxdepth 2 -type d -name '*.app')
+ if [ "${#apps[@]}" -ne 1 ]; then
+ echo "::error::expected exactly one .app under release/, found ${#apps[@]}"
+ printf '%s\n' "${apps[@]}"
+ exit 1
+ fi
+ app="${apps[0]}"
+ codesign --verify --deep --strict --verbose=2 "$app"
+ # The stapled ticket is what lets a Mac clear the app offline; without it
+ # the first launch is a Gatekeeper prompt however well-signed the bundle is.
+ xcrun stapler validate "$app"
+ # `spctl --assess` reports a rejected build as accepted when assessment is
+ # switched off on the machine, so the assessment is worth nothing until
+ # this says it is on.
+ status="$(spctl --status 2>&1)"
+ echo "$status"
+ case "$status" in
+ *"assessments enabled"*) ;;
+ *) echo "::error::Gatekeeper assessment is off on this runner ($status) — spctl --assess cannot be trusted here"; exit 1 ;;
+ esac
+ spctl --assess --type execute --verbose=4 "$app"
- name: Upload to GitHub Release
if: startsWith(github.ref, 'refs/tags/')
@@ -162,26 +265,100 @@ jobs:
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
- # Upload the installable artifacts (.dmg, .zip) AND the channel manifest
- # (latest-mac.yml) + blockmaps — electron-updater needs the manifest to
- # detect/download updates, so a dmg-only release would silently break
- # auto-update.
+ # Installers and blockmaps only. `latest-mac.yml` is deliberately absent:
+ # unlike Linux, macOS has no per-arch channel file, so both arches write
+ # that one name and the second upload would replace the first — leaving
+ # the overwritten architecture with an update feed that never offers it
+ # anything. merge-mac-manifest publishes the combined manifest instead.
shopt -s nullglob
- assets=(release/*.dmg release/*.zip release/*.blockmap release/latest-mac.yml)
+ assets=(release/*.dmg release/*.zip release/*.blockmap)
gh release upload "$GITHUB_REF_NAME" "${assets[@]}" \
--repo "$GITHUB_REPOSITORY" \
--clobber
+ - name: Upload the channel manifest for merging
+ # Every run, tag or dispatch: this is the merge job's only input, and a
+ # dispatch run is where a broken manifest should surface.
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+ with:
+ name: mac-update-manifest-${{ matrix.arch }}
+ path: console/apps/switch-console-desktop/release/latest-mac.yml
+ if-no-files-found: error
+
- name: Upload build artifacts (dispatch runs, no Release)
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
- name: switch-console-macos-arm64
+ name: switch-console-macos-${{ matrix.arch }}
path: |
console/apps/switch-console-desktop/release/*.dmg
console/apps/switch-console-desktop/release/*.zip
if-no-files-found: error
+ # electron-updater reads exactly one macOS channel file, `latest-mac.yml`, and
+ # chooses a download from its `files` list by whether the file name contains
+ # `arm64`. One manifest listing both architectures is therefore the shape it
+ # wants — and the shape electron-builder itself emits when a single invocation
+ # builds both. Two native builds cannot produce it between them, so the two
+ # per-arch manifests are combined here.
+ merge-mac-manifest:
+ name: Merge the macOS channel manifest
+ runs-on: ubuntu-latest
+ needs: build-macos
+ # Skipped when either mac job failed or was skipped, which leaves no
+ # latest-mac.yml on the Release and stops publish-release.
+ if: ${{ !cancelled() && needs.build-macos.result == 'success' }}
+ steps:
+ - name: Checkout
+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+ - name: Setup pnpm
+ uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0
+ with:
+ version: 11.5.3
+
+ - name: Setup Node
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+ with:
+ node-version-file: console/.nvmrc
+ cache: pnpm
+ cache-dependency-path: console/pnpm-lock.yaml
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Download the per-arch manifests
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+ with:
+ pattern: mac-update-manifest-*
+ path: mac-manifests
+
+ - name: Merge into one latest-mac.yml
+ working-directory: console/apps/switch-console-desktop
+ run: |
+ node --experimental-strip-types scripts/merge-mac-update-manifest.ts \
+ --out "$RUNNER_TEMP/latest-mac.yml" \
+ arm64="$GITHUB_WORKSPACE/mac-manifests/mac-update-manifest-arm64/latest-mac.yml" \
+ x64="$GITHUB_WORKSPACE/mac-manifests/mac-update-manifest-x64/latest-mac.yml"
+ cat "$RUNNER_TEMP/latest-mac.yml"
+
+ - name: Upload to GitHub Release
+ if: startsWith(github.ref, 'refs/tags/')
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ gh release upload "$GITHUB_REF_NAME" "$RUNNER_TEMP/latest-mac.yml" \
+ --repo "$GITHUB_REPOSITORY" \
+ --clobber
+
+ - name: Upload the merged manifest (dispatch runs, no Release)
+ if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+ with:
+ name: switch-console-macos-manifest
+ path: ${{ runner.temp }}/latest-mac.yml
+ if-no-files-found: error
+
build-linux:
name: Build & release (Linux ${{ matrix.arch }})
runs-on: ${{ matrix.runner }}
@@ -366,7 +543,7 @@ jobs:
publish-release:
name: Publish GitHub Release
runs-on: ubuntu-latest
- needs: [create-release, build-macos, build-linux, build-windows]
+ needs: [create-release, build-macos, merge-mac-manifest, build-linux, build-windows]
if: startsWith(github.ref, 'refs/tags/')
# This job never checks out, so the workflow-level `console` working directory
# does not exist for it.
@@ -392,6 +569,28 @@ jobs:
exit 1
fi
+ - name: Verify the macOS manifest covers both architectures
+ # Presence is not enough for macOS: both mac builds write `latest-mac.yml`,
+ # so a single-arch manifest is what a regression here looks like — and it
+ # is silent, because the architecture that is missing keeps checking for
+ # updates and simply never finds one it can install.
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ gh release download "$GITHUB_REF_NAME" \
+ --repo "$GITHUB_REPOSITORY" \
+ --pattern latest-mac.yml \
+ --dir "$RUNNER_TEMP"
+ cat "$RUNNER_TEMP/latest-mac.yml"
+ missing=""
+ for required in -arm64.zip -x64.zip; do
+ grep -q "url: .*$required$" "$RUNNER_TEMP/latest-mac.yml" || missing="$missing $required"
+ done
+ if [ -n "$missing" ]; then
+ echo "::error::Refusing to publish $GITHUB_REF_NAME — latest-mac.yml lists no:$missing. That architecture would receive no further updates, without an error anywhere. The Release stays a draft."
+ exit 1
+ fi
+
- name: Publish
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/RELEASING.md b/RELEASING.md
index aba8edd38..22d77b7e2 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -90,11 +90,17 @@ The desktop app (`console/`) releases on its own tag, `switch-console-v<version>
`console/apps/switch-console-desktop/package.json` `version` (the workflow verifies
this and fails on mismatch). Procedure: bump `package.json`, cut the
`## switch-console` `CHANGELOG.md` section, merge to `main`, tag, push. The workflow
-publishes a **GitHub Release** (macOS arm64 signed + notarized; Linux x64 and
-arm64 AppImage/deb/rpm, unsigned — one job per arch, each on a runner of that
-arch).
+publishes a **GitHub Release** (macOS arm64 and x64, signed + notarized; Linux
+x64 and arm64 AppImage/deb/rpm, unsigned — one job per arch, each on a runner of
+that arch).
-**Approval gate (required).** The `build-macos` job runs in the GitHub
+macOS also gets a `merge-mac-manifest` job. electron-updater reads one channel
+file for macOS, `latest-mac.yml`, so the two mac jobs upload installers only and
+that job publishes a single manifest listing both architectures. `publish-release`
+refuses to publish if the manifest names only one of them: the missing
+architecture would go on checking for updates and silently never install another.
+
+**Approval gate (required).** Both `build-macos` matrix jobs run in the GitHub
`release` environment (required reviewers), which holds the Apple signing /
notarization secrets. On tag push the (assetless) GitHub Release is created and
the Linux build runs immediately, but the **signed + notarized macOS
diff --git a/console/AGENTS.md b/console/AGENTS.md
index 8f5f52d65..d4832f2b6 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -181,7 +181,8 @@ Package desktop artifacts locally:
```bash
pnpm run package
-pnpm run package:mac
+pnpm run package:mac # arm64
+pnpm run package:mac:x64
pnpm run package:linux # x64
pnpm run package:linux:arm64
pnpm run package:win
@@ -198,9 +199,19 @@ Two things these scripts do NOT do for you:
`pnpm --filter @switch-console/desktop run rebuild` last produced is what
gets copied into the package.
-The Linux scripts name an arch for that second reason: the natives are built for
-the host, so packaging the other arch yields a package that installs, launches,
-and dies on the first wrong-arch `.node`. Build each arch on that arch.
+The macOS and Linux scripts name an arch for that second reason: the natives are
+built for the host, so packaging the other arch yields a package that installs,
+launches, and dies on the first wrong-arch `.node`. Build each arch on that arch
+— which is also why the release workflow runs macOS twice, on an Apple silicon
+runner and an Intel one, rather than passing both flags to one job.
+
+The two macOS builds share one auto-update channel file. electron-builder writes
+`latest-mac.yml` for every macOS arch (the per-arch suffix it gives Linux is
+Linux-only), so neither release job publishes its own — `merge-mac-manifest`
+combines them into one manifest listing both, which is what electron-updater
+reads and how it routes each Mac to its own build. Anything that changes macOS
+artifact names has to keep `arm64` in the Apple silicon file names: that
+substring is the whole of the updater's routing rule.
Run formatting, linting, type checks, and tests:
diff --git a/console/agents/risky-areas/updater.md b/console/agents/risky-areas/updater.md
index 5534e5e6b..5b2c7ee95 100644
--- a/console/agents/risky-areas/updater.md
+++ b/console/agents/risky-areas/updater.md
@@ -4,8 +4,8 @@
- `src/main/core/updates/update-service.ts`
- `src/main/core/updates/controller.ts`
-- `src/main/core/updates/github-token.ts` — the updater's `gh` CLI token
- `src/main/core/updates/dev-harness.ts` — `SWITCHDASH_FAKE_UPDATE` replay
+- `scripts/merge-mac-update-manifest.ts` — the merged macOS channel manifest
- `build/`
- `package.json`
- `electron-builder.config.ts`
@@ -46,15 +46,44 @@ The workflow does **not** let electron-builder publish (`--publish never`). Inst
electron-updater — `/releases/latest` skips drafts — so no client can see a
half-uploaded release.
2. Each platform job builds, then `gh release upload`s its installers **and** its
- electron-updater channel manifest.
+ electron-updater channel manifest — except macOS, whose two jobs upload installers
+ only and leave the manifest to `merge-mac-manifest` (see below).
3. `publish-release` runs last. It **verifies every expected channel manifest is
present** and refuses to publish if any is missing, leaving the release a draft with
- an error naming what's absent.
+ an error naming what's absent. For macOS it also checks the manifest names both
+ architectures, since presence alone cannot tell a merged manifest from a
+ single-arch one.
That last step is the guard worth knowing about: binaries published against a stale or
missing channel manifest produce sha512 checksum failures on client download, so the
pipeline would rather stay a draft than publish an inconsistent release.
+### macOS: one manifest, two architectures
+
+macOS ships two builds, arm64 and x64, and they share a **single** channel file.
+electron-builder suffixes the channel file per architecture on Linux only
+(`latest-linux-arm64.yml`); on macOS every architecture writes `latest-mac.yml`.
+There is no `latest-mac-x64.yml` to reach for, and giving one architecture its own
+`channel` would not help either — `update-service.ts` calls `setFeedURL` with a bare
+provider descriptor, so whatever channel the packaged `app-update.yml` carries is
+discarded at runtime.
+
+So the release workflow builds each architecture on a runner of that architecture,
+neither job publishes a manifest, and `merge-mac-manifest` combines the two into one
+`latest-mac.yml` listing both. That is the shape electron-updater expects: its mac path
+filters the manifest's `files` by whether the file name contains `arm64` — Intel drops
+those entries, Apple silicon (including under Rosetta) prefers them.
+
+Two consequences worth holding on to:
+
+- **`arm64` in the file name is the routing rule.** Rename the macOS artifacts without
+ it and every Mac is offered the wrong build.
+- **The failure mode is silent.** An architecture missing from the manifest still passes
+ the version check and only fails at download, with
+ `ERR_UPDATER_NO_FILES_PROVIDED` — which a background check surfaces as a tinted
+ sidebar indicator and nothing else. Hence the both-architectures check in
+ `publish-release` rather than trusting the upload steps.
+
### `UPDATE_CHANNEL` is a log label, not a feed selector
`UPDATE_CHANNEL` (`src/shared/app-identity.ts`) is `'v1-stable'` / `'v1-canary'` — naming
@@ -86,5 +115,7 @@ one until the app restarts.
## Current Notes
-- macOS and Linux release builds rebuild native modules for the target Electron version
+- macOS and Linux release builds rebuild native modules for the target Electron version,
+ on a runner of the architecture they are building for — `npmRebuild` is off, so a
+ cross-built package carries the build machine's `.node` files and dies on first use
- changelog and auto-update behavior are separate but related surfaces in the app
diff --git a/console/apps/switch-console-desktop/electron-builder.config.ts b/console/apps/switch-console-desktop/electron-builder.config.ts
index b78b07a07..404c47a0f 100644
--- a/console/apps/switch-console-desktop/electron-builder.config.ts
+++ b/console/apps/switch-console-desktop/electron-builder.config.ts
@@ -99,10 +99,12 @@ const config: Configuration = {
hardenedRuntime: true,
entitlements: 'build/entitlements.mac.plist',
entitlementsInherit: 'build/entitlements.mac.plist',
- target: [
- { target: 'dmg', arch: ['arm64'] },
- { target: 'zip', arch: ['arm64'] },
- ],
+ // No `arch` here, for the same reason as `linux` below: naming an arch makes
+ // every invocation build it and ignore the `--x64` / `--arm64` flag, and
+ // `npmRebuild: false` means the package carries whatever native modules the
+ // earlier `pnpm rebuild` produced for the host. The release workflow builds
+ // each arch on a runner of that arch and passes the matching flag.
+ target: ['dmg', 'zip'],
icon: 'src/assets/images/switch-console/switch-console-beta.icns',
// electron-builder reads the App Store Connect API key from APPLE_API_KEY
// (path to .p8) / APPLE_API_KEY_ID / APPLE_API_ISSUER when notarize is on.
diff --git a/console/apps/switch-console-desktop/package.json b/console/apps/switch-console-desktop/package.json
index 34790c503..eb2150c70 100644
--- a/console/apps/switch-console-desktop/package.json
+++ b/console/apps/switch-console-desktop/package.json
@@ -35,7 +35,8 @@
"sync:compose:check": "node scripts/sync-standalone-compose.mjs --check",
"build:renderer": "electron-vite build --filter renderer",
"package": "pnpm run build && electron-builder --config electron-builder.config.ts",
- "package:mac": "pnpm run build && electron-builder --mac --config electron-builder.config.ts",
+ "package:mac": "pnpm run build && electron-builder --mac --arm64 --publish never --config electron-builder.config.ts",
+ "package:mac:x64": "pnpm run build && electron-builder --mac --x64 --publish never --config electron-builder.config.ts",
"package:linux": "pnpm run build && electron-builder --linux --x64 --publish never --config electron-builder.config.ts",
"package:linux:arm64": "pnpm run build && electron-builder --linux --arm64 --publish never --config electron-builder.config.ts",
"package:win": "pnpm run build && electron-builder --win --publish never --config electron-builder.config.ts",
@@ -115,6 +116,7 @@
"electron-builder": "^26.8.1",
"electron-vite": "^5.0.0",
"framer-motion": "^12.33.0",
+ "js-yaml": "^5.3.0",
"jsdom": "^29.0.2",
"katex": "^0.16.45",
"lucide-react": "^0.564.0",
diff --git a/console/apps/switch-console-desktop/scripts/merge-mac-update-manifest.test.ts b/console/apps/switch-console-desktop/scripts/merge-mac-update-manifest.test.ts
new file mode 100644
index 000000000..91685f36b
--- /dev/null
+++ b/console/apps/switch-console-desktop/scripts/merge-mac-update-manifest.test.ts
@@ -0,0 +1,121 @@
+import { load } from 'js-yaml';
+import { describe, expect, it } from 'vitest';
+import {
+ type ManifestInput,
+ type UpdateManifest,
+ mergeMacUpdateManifests,
+} from './merge-mac-update-manifest';
+
+function manifest(arch: string, version = '0.28.0'): string {
+ return [
+ `version: ${version}`,
+ 'files:',
+ ` - url: switch-console-${arch}.zip`,
+ ' sha512: zip-checksum-' + arch,
+ ' size: 147344955',
+ ` - url: switch-console-${arch}.dmg`,
+ ' sha512: dmg-checksum-' + arch,
+ ' size: 148693658',
+ `path: switch-console-${arch}.zip`,
+ `sha512: zip-checksum-${arch}`,
+ "releaseDate: '2026-08-18T08:53:14.463Z'",
+ '',
+ ].join('\n');
+}
+
+function input(arch: string, text = manifest(arch)): ManifestInput {
+ return { arch, source: `${arch}/latest-mac.yml`, text };
+}
+
+describe('mergeMacUpdateManifests', () => {
+ it('lists every architecture in one manifest', () => {
+ const merged = load(mergeMacUpdateManifests([input('arm64'), input('x64')])) as UpdateManifest;
+
+ expect(merged.files.map((file) => file.url)).toEqual([
+ 'switch-console-arm64.zip',
+ 'switch-console-arm64.dmg',
+ 'switch-console-x64.zip',
+ 'switch-console-x64.dmg',
+ ]);
+ });
+
+ it('keeps the first input as the base document', () => {
+ const merged = load(mergeMacUpdateManifests([input('arm64'), input('x64')])) as UpdateManifest;
+
+ expect(merged.version).toBe('0.28.0');
+ expect(merged.path).toBe('switch-console-arm64.zip');
+ expect(merged.sha512).toBe('zip-checksum-arm64');
+ expect(merged.releaseDate).toBe('2026-08-18T08:53:14.463Z');
+ });
+
+ it('leaves each architecture a zip to install from', () => {
+ const merged = load(mergeMacUpdateManifests([input('arm64'), input('x64')])) as UpdateManifest;
+ const forIntel = merged.files.filter((file) => !file.url.includes('arm64'));
+ const forAppleSilicon = merged.files.filter((file) => file.url.includes('arm64'));
+
+ expect(forIntel.some((file) => file.url.endsWith('.zip'))).toBe(true);
+ expect(forAppleSilicon.some((file) => file.url.endsWith('.zip'))).toBe(true);
+ });
+
+ it('refuses a manifest whose files contradict its declared architecture', () => {
+ expect(() =>
+ mergeMacUpdateManifests([input('arm64'), input('x64', manifest('arm64'))])
+ ).toThrow(/declared x64 but lists 'switch-console-arm64.zip'/);
+ });
+
+ it('refuses to publish without the arm64 manifest', () => {
+ expect(() => mergeMacUpdateManifests([input('x64'), input('universal')])).toThrow(
+ /no arm64 manifest/
+ );
+ });
+
+ it('refuses manifests built from different versions', () => {
+ expect(() =>
+ mergeMacUpdateManifests([input('arm64'), input('x64', manifest('x64', '0.27.1'))])
+ ).toThrow(/version mismatch/);
+ });
+
+ it('refuses a single manifest', () => {
+ expect(() => mergeMacUpdateManifests([input('arm64')])).toThrow(/at least two manifests/);
+ });
+
+ it('refuses an architecture that produced no zip', () => {
+ const dmgOnly = [
+ 'version: 0.28.0',
+ 'files:',
+ ' - url: switch-console-x64.dmg',
+ ' sha512: dmg-checksum-x64',
+ ' size: 148693658',
+ 'path: switch-console-x64.dmg',
+ 'sha512: dmg-checksum-x64',
+ "releaseDate: '2026-08-18T08:53:14.463Z'",
+ '',
+ ].join('\n');
+
+ expect(() => mergeMacUpdateManifests([input('arm64'), input('x64', dmgOnly)])).toThrow(
+ /lists no .zip/
+ );
+ });
+
+ it('refuses a file entry with no checksum', () => {
+ const noChecksum = [
+ 'version: 0.28.0',
+ 'files:',
+ ' - url: switch-console-x64.zip',
+ ' size: 147344955',
+ 'path: switch-console-x64.zip',
+ "releaseDate: '2026-08-18T08:53:14.463Z'",
+ '',
+ ].join('\n');
+
+ expect(() => mergeMacUpdateManifests([input('arm64'), input('x64', noChecksum)])).toThrow(
+ /without a sha512/
+ );
+ });
+
+ it('refuses an empty manifest', () => {
+ expect(() =>
+ mergeMacUpdateManifests([input('arm64'), input('x64', 'version: 0.28.0\nfiles: []\n')])
+ ).toThrow(/lists no files/);
+ });
+});
diff --git a/console/apps/switch-console-desktop/scripts/merge-mac-update-manifest.ts b/console/apps/switch-console-desktop/scripts/merge-mac-update-manifest.ts
new file mode 100644
index 000000000..014185d30
--- /dev/null
+++ b/console/apps/switch-console-desktop/scripts/merge-mac-update-manifest.ts
@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Combine the per-architecture macOS update manifests into the single
+ * `latest-mac.yml` electron-updater reads.
+ *
+ * node --experimental-strip-types scripts/merge-mac-update-manifest.ts \
+ * --out latest-mac.yml arm64=<path> x64=<path>
+ *
+ * electron-builder gives Linux a per-arch channel file (`latest-linux-arm64.yml`)
+ * but macOS none — `getArchPrefixForUpdateFile` returns an empty suffix for every
+ * platform except Linux, so an arm64 build and an x64 build both write
+ * `latest-mac.yml`. Uploading both to a Release leaves whichever finished last as
+ * the only manifest, and the other architecture stops receiving updates with no
+ * error anywhere: the version check still passes, and the download then fails
+ * with ERR_UPDATER_NO_FILES_PROVIDED once the updater has filtered the file list
+ * down to nothing.
+ *
+ * electron-updater's mac path expects one manifest listing every architecture. It
+ * picks a download by looking for `arm64` in the file name — Intel machines drop
+ * those entries, Apple silicon (including under Rosetta) prefers them — so the
+ * two manifests are combined here rather than published separately.
+ *
+ * The first input is the base document: its `version`, `releaseDate` and the
+ * legacy top-level `path`/`sha512` survive, and every other input contributes
+ * only its `files` entries. Pass arm64 first, so those top-level fields keep
+ * naming what they have always named. They can only ever name one architecture,
+ * so they are wrong for the other by construction — which is harmless because
+ * every client reads `files`; `path` is only consulted for a manifest that has no
+ * `files` at all.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dump, load } from 'js-yaml';
+
+export interface UpdateManifestFile {
+ url: string;
+ sha512: string;
+ size: number;
+ [key: string]: unknown;
+}
+
+export interface UpdateManifest {
+ version: string;
+ files: UpdateManifestFile[];
+ path: string;
+ sha512: string;
+ releaseDate: string;
+ [key: string]: unknown;
+}
+
+export interface ManifestInput {
+ /** Architecture the manifest was built for, as electron-builder names it. */
+ arch: string;
+ /** Where it came from, for error messages. */
+ source: string;
+ text: string;
+}
+
+const ARM64_MARKER = 'arm64';
+
+function fail(message: string): never {
+ throw new Error(`merge-mac-update-manifest: ${message}`);
+}
+
+function parseManifest(input: ManifestInput): UpdateManifest {
+ let parsed: unknown;
+ try {
+ parsed = load(input.text);
+ } catch (cause) {
+ fail(`${input.source} is not valid YAML: ${(cause as Error).message}`);
+ }
+ if (parsed === null || typeof parsed !== 'object') {
+ fail(`${input.source} does not contain a mapping`);
+ }
+ const manifest = parsed as UpdateManifest;
+ if (typeof manifest.version !== 'string' || manifest.version === '') {
+ fail(`${input.source} has no version`);
+ }
+ if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+ fail(`${input.source} lists no files`);
+ }
+ for (const file of manifest.files) {
+ if (file === null || typeof file !== 'object' || typeof file.url !== 'string') {
+ fail(`${input.source} has a file entry without a url`);
+ }
+ // electron-updater rejects a checksum-less entry with ERR_UPDATER_NO_CHECKSUM
+ // on the user's machine. Catch it while it is still a build failure.
+ if (typeof file.sha512 !== 'string' || file.sha512 === '') {
+ fail(`${input.source} lists '${file.url}' without a sha512`);
+ }
+ }
+ return manifest;
+}
+
+/**
+ * The routing rule electron-updater applies, asserted at build time: an arm64
+ * manifest must name arm64 in every url, and no other architecture may. A build
+ * that violates it produces a manifest that sends one architecture the other's
+ * download.
+ */
+function assertArchNaming(input: ManifestInput, manifest: UpdateManifest): void {
+ const wantsArm64 = input.arch === ARM64_MARKER;
+ for (const file of manifest.files) {
+ const namesArm64 = file.url.includes(ARM64_MARKER);
+ if (namesArm64 !== wantsArm64) {
+ fail(
+ `${input.source} was declared ${input.arch} but lists '${file.url}'. ` +
+ `electron-updater routes macOS downloads on whether the file name contains '${ARM64_MARKER}', ` +
+ `so this manifest would send the wrong build to one architecture.`
+ );
+ }
+ }
+ if (!manifest.files.some((file) => file.url.endsWith('.zip'))) {
+ fail(
+ `${input.source} lists no .zip — electron-updater installs macOS updates from the zip, not the dmg`
+ );
+ }
+}
+
+export function mergeMacUpdateManifests(inputs: ManifestInput[]): string {
+ if (inputs.length < 2) {
+ fail(`expected at least two manifests to merge, got ${inputs.length}`);
+ }
+ if (!inputs.some((input) => input.arch === ARM64_MARKER)) {
+ fail(
+ `no ${ARM64_MARKER} manifest among the inputs — refusing to publish a macOS manifest without it`
+ );
+ }
+
+ const [base, ...rest] = inputs.map((input) => {
+ const manifest = parseManifest(input);
+ assertArchNaming(input, manifest);
+ return { input, manifest };
+ });
+
+ const files: UpdateManifestFile[] = [];
+ const seen = new Map<string, string>();
+ for (const { input, manifest } of [base, ...rest]) {
+ if (manifest.version !== base.manifest.version) {
+ fail(
+ `version mismatch: ${base.input.source} is ${base.manifest.version}, ` +
+ `${input.source} is ${manifest.version}`
+ );
+ }
+ for (const file of manifest.files) {
+ const previous = seen.get(file.url);
+ if (previous !== undefined) {
+ fail(`'${file.url}' appears in both ${previous} and ${input.source}`);
+ }
+ seen.set(file.url, input.source);
+ files.push(file);
+ }
+ }
+
+ // `lineWidth` matches builder-util's own serializeToYaml, so the merged file is
+ // written the way electron-builder writes the ones it feeds in — at the default
+ // width a sha512 wraps into a folded block scalar.
+ return dump({ ...base.manifest, files }, { lineWidth: 8000 });
+}
+
+function parseArgs(argv: string[]): { out: string; inputs: ManifestInput[] } {
+ let out = '';
+ const inputs: ManifestInput[] = [];
+ for (let index = 0; index < argv.length; index += 1) {
+ const arg = argv[index];
+ if (arg === '--out') {
+ out = argv[index + 1] ?? '';
+ index += 1;
+ continue;
+ }
+ const separator = arg.indexOf('=');
+ if (separator <= 0) {
+ fail(`unrecognised argument '${arg}' — expected --out <path> and <arch>=<path> pairs`);
+ }
+ const path = arg.slice(separator + 1);
+ inputs.push({ arch: arg.slice(0, separator), source: path, text: readFileSync(path, 'utf8') });
+ }
+ if (out === '') {
+ fail('--out <path> is required');
+ }
+ return { out, inputs };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ const { out, inputs } = parseArgs(process.argv.slice(2));
+ writeFileSync(out, mergeMacUpdateManifests(inputs));
+ console.log(
+ `merge-mac-update-manifest: wrote ${out} from ${inputs.map((i) => i.arch).join(', ')}`
+ );
+}
diff --git a/console/apps/switch-console-desktop/scripts/postinstall.ts b/console/apps/switch-console-desktop/scripts/postinstall.ts
index 48a92bd60..b8bbc2f08 100644
--- a/console/apps/switch-console-desktop/scripts/postinstall.ts
+++ b/console/apps/switch-console-desktop/scripts/postinstall.ts
@@ -42,7 +42,7 @@ function getElectronRebuildBin() {
return path.join(appRoot, 'node_modules', '.bin', binName);
}
-function runElectronRebuild(onlyModules) {
+function runElectronRebuild(onlyModules: string[]) {
const electronRebuildBin = getElectronRebuildBin();
const args = ['-f'];
diff --git a/console/apps/switch-console-desktop/tsconfig.json b/console/apps/switch-console-desktop/tsconfig.json
index 2ba0eb68c..a05ddc6f7 100644
--- a/console/apps/switch-console-desktop/tsconfig.json
+++ b/console/apps/switch-console-desktop/tsconfig.json
@@ -24,7 +24,8 @@
"src/sidecar/**/*",
"src/types/**/*",
"src/test/**/*",
- "tooling/**/*"
+ "tooling/**/*",
+ "scripts/**/*"
],
"exclude": ["node_modules", "dist", "out", "**/_*/**"]
}
diff --git a/console/apps/switch-console-desktop/vitest.config.ts b/console/apps/switch-console-desktop/vitest.config.ts
index 07bd4ef91..984a6e10b 100644
--- a/console/apps/switch-console-desktop/vitest.config.ts
+++ b/console/apps/switch-console-desktop/vitest.config.ts
@@ -33,7 +33,7 @@ export default defineConfig({
test: {
name: 'node',
environment: 'node',
- include: ['src/**/*.test.ts'],
+ include: ['src/**/*.test.ts', 'scripts/**/*.test.ts'],
exclude: [
'**/_*/**',
'src/renderer/tests/browser/**',
diff --git a/console/docs/INSTALL.md b/console/docs/INSTALL.md
index d40a6d939..02b832159 100644
--- a/console/docs/INSTALL.md
+++ b/console/docs/INSTALL.md
@@ -4,8 +4,8 @@ Switch Console is distributed as a desktop app through **GitHub Releases on this
repository** (`sandbox-quantum/switch`). The repo is public, so the downloads
need no account, token or sign-up. No need to build from source.
-> Builds are currently **macOS arm64** (Apple Silicon), **Linux x64 and arm64**
-> and **Windows x64**. Windows builds are not code signed — see
+> Builds are currently **macOS arm64 (Apple Silicon) and x64 (Intel)**, **Linux
+> x64 and arm64** and **Windows x64**. Windows builds are not code signed — see
> [Install (Windows x64)](#install-windows-x64).
## Download
@@ -25,8 +25,10 @@ need no account, token or sign-up. No need to build from source.
Release assets are public, so a plain `curl` works — no token, no `gh`:
```bash
-# Download an installer from a specific release (macOS):
+# Download an installer from a specific release (macOS — Apple Silicon):
curl -fLO https://github.com/sandbox-quantum/switch/releases/download/switch-console-v<version>/switch-console-arm64.dmg
+# macOS on Intel:
+curl -fLO https://github.com/sandbox-quantum/switch/releases/download/switch-console-v<version>/switch-console-x64.dmg
# Linux — pick the format your distro uses:
curl -fLO https://github.com/sandbox-quantum/switch/releases/download/switch-console-v<version>/switch-console-x86_64.AppImage
@@ -46,11 +48,22 @@ gh release download switch-console-v<version> \
## Install (macOS)
+Two `.dmg` files are published — take the one matching your Mac:
+
+| Mac | Asset |
+| --- | --- |
+| Apple Silicon (M1 and later) | `switch-console-arm64.dmg` |
+| Intel | `switch-console-x64.dmg` |
+
+Apple menu → **About This Mac** names the chip if you are unsure; `uname -m`
+prints `arm64` or `x86_64`.
+
1. Open the downloaded `.dmg`.
2. Drag **Switch Console** into your **Applications** folder.
Tagged macOS releases are signed and notarized with SandboxAQ's Developer ID, so
-they open without a Gatekeeper bypass.
+they open without a Gatekeeper bypass. Both architectures receive in-app updates,
+each one offered its own build.
## Install (Linux)
@@ -159,7 +172,7 @@ pnpm install
pnpm run build # workspace packages, then the app
pnpm --filter @switch-console/desktop run rebuild # native modules for THIS machine
cd apps/switch-console-desktop
-pnpm run package:linux # or package:linux:arm64 / package:mac / package:win
+pnpm run package:linux # or package:linux:arm64 / package:mac / package:mac:x64 / package:win
```
The first two steps are not optional. Packaging from the app directory alone
diff --git a/console/pnpm-lock.yaml b/console/pnpm-lock.yaml
index 1c5a453a9..1901be7f0 100644
--- a/console/pnpm-lock.yaml
+++ b/console/pnpm-lock.yaml
@@ -200,6 +200,9 @@ importers:
framer-motion:
specifier: ^12.33.0
+ js-yaml:
+ specifier: ^5.3.0
+ version: 5.3.0
jsdom:
specifier: ^29.0.2
version: 29.1.1(@noble/[email protected])
@@ -3981,6 +3984,10 @@ packages:
resolution: {integrity: sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==}
hasBin: true
+ resolution: {integrity: sha512-muutsYr+e2+d3rTgUGslq5rxbBlUy3cJ61IsHag2QNDQV+7zXWjkUpmALIajhrlLlrgRUiymj6U3zUr/TMK84Q==}
+ hasBin: true
+
resolution: {integrity: sha512-ECi4Fi2f7BdJtUKTflYRTiaMxIB0O6zfR1fX0GXpUrf6flp8QIYn1UT20YQqdSOfk2dfkCwS8LAFoJDEppNK5Q==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24.0.0}
@@ -9079,6 +9086,10 @@ snapshots:
dependencies:
argparse: 2.0.1
+ dependencies:
+ argparse: 2.0.1
+
dependencies:
'@asamuzakjp/css-color': 5.1.11