Skip to content

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

docs(switchdash): describe the release pipeline that exists (CHOO-1860)

Louis Amaudruz4deb43b87854
diff --git a/dash/AGENTS.md b/dash/AGENTS.md
index 6a4c3b3ea..86602e6a2 100644
--- a/dash/AGENTS.md
+++ b/dash/AGENTS.md
@@ -1,8 +1,8 @@
# Project Overview
Switchdash is a cross-platform, local-first Electron app for orchestrating multiple AI
-coding agents in parallel. Each agent runs in its own session at the project root (there
-are no Git worktrees). An agent runs either locally or — when configured remote — on an
+coding agents in parallel. Each agent runs in its own session in its location's directory
+(there are no Git worktrees). An agent runs either locally or — when configured remote — on an
SSH host, where it runs inside tmux next to a switchdash-deployed sidecar so it keeps
working and listening to its Switch rooms while switchdash is closed (CHOO-1059). It
combines provider-agnostic CLI agent execution, session management,
@@ -34,10 +34,14 @@ Repo root:
- `.claude/` - Local Claude agent settings for this checkout.
- `agents/` - Agent-facing architecture, workflow, convention, integration, and risk docs.
- `apps/switchdash-desktop/` - The Electron desktop app (everything below).
-- `packages/` - Shared workspace packages: core runtime, shared primitives, and plugins.
+- `packages/` - Shared workspace packages.
- `packages/core/` - Transport-agnostic core runtime primitives.
- - `packages/shared/` - Shared workspace primitives.
- - `packages/plugins/` - Plugin interfaces and helpers.
+ - `packages/shared/` - Shared workspace primitives, including the `Result<T, E>` type
+ (`@switchdash/shared`).
+ - `packages/plugins/` - Plugin interfaces and helpers, and the agent provider plugins
+ under `src/agents/impl/<id>/`.
+ - `packages/switch-agent-runtime/` - The published agent runtime; sessions run a pinned
+ version of it (see "Versioned Artifacts").
- Root config files - `pnpm-workspace.yaml`, root `package.json` with aggregate scripts,
`.nvmrc`, `.oxfmtrc.json`, `.oxlintrc.json`.
@@ -45,7 +49,9 @@ Inside `apps/switchdash-desktop/`:
- `build/` - Electron packaging assets; avoid edits unless working on packaging or signing.
- `drizzle/` - Generated Drizzle SQL migrations and metadata.
-- `scripts/` - Release, verification, and build support scripts.
+- `scripts/` - Build and verification support scripts (sidecar bundle, postinstall,
+ deeplink reset, compose sync). Releasing is a GitHub Actions workflow at the repo
+ root, not a script here.
- `src/main/` - Electron main process, RPC controllers, services, database, PTY.
- `src/preload/` - Typed Electron preload bridge exposed to the renderer.
- `src/renderer/` - React app organized around `app/`, `features/`, `lib/`, and tests.
@@ -183,7 +189,7 @@ pnpm run reset
imported operation or service functions.
- Renderer RPC calls go through `rpc` from `src/renderer/lib/ipc.ts`.
- Feature UI lives under `src/renderer/features/<feature>/`; shared renderer
- primitives, stores, hooks, modal infrastructure, PTY, Monaco, and UI live under
+ primitives, stores, hooks, modal infrastructure, PTY, hotkeys, and UI live under
`src/renderer/lib/`.
- New modals must be registered in `src/renderer/app/modal-registry.ts`.
- New views must be registered in `src/renderer/app/view-registry.ts`.
@@ -225,12 +231,16 @@ views, modals, command providers, project state, terminals, and session workflow
Shared IPC primitives, provider metadata, events, MCP types, skills types, and
domain types live under `src/shared/`.
-agent runtime, dependencies, execution context, fs, locations (an agent's working
-dir on a host — formerly the project/workspace split), prompt library, PTY,
-resource monitor, search, secrets, sessions, settings, switch agents, terminal
-shell, terminals, updates, and view state. Stateful main-process concerns use
-singleton services; expected failures should use the `Result<T, E>` pattern from
-`src/main/lib/result.ts`.
+Main-process work is split into domain modules under `src/main/core/`: agent hooks,
+agent runtime, agents (Switch agents), app, dependencies, execution context, fs,
+locations (an agent's working dir on a host — formerly the project/workspace split),
+managed Switch server, prompt library, providers (the CLI-provider registry), PTY,
+remote hosts, resource monitor, search, secrets, sessions, settings, sidecar, SSH,
+switch rooms, switch servers, switch setup, terminal shell, terminals, updates, and
+view state. `agents` and `providers` are different things — see
+`agents/architecture/main-process.md`. Stateful main-process concerns use singleton
+services; expected failures should use the `Result<T, E>` pattern from the
+`@switchdash/shared` workspace package.
### Logging
@@ -304,7 +314,7 @@ pnpm run lint
## Security & Compliance
-- The project is licensed under Apache-2.0; see `LICENSE.md`.
+- The project is licensed under Apache-2.0; see `LICENSE` at the repo root.
- Do not commit secrets, tokens, private keys, app databases, logs, build artifacts,
or generated dependency folders.
- Application secrets are stored through encrypted app secret services and Electron
@@ -451,7 +461,8 @@ pnpm run test
display metadata, and a mirror of each provider's argv shape. The mirror is
descriptive: nothing reads it at spawn time, so change the plugin first and update the
mirror to match. `provider-argv-parity.test.ts` pins Codex's.
-- Provider detection lives in `src/main/core/dependencies/dependency-manager.ts`.
+- Provider detection lives in `src/main/core/dependencies/` (`dependency-managers.ts`,
+ `registry.ts`), with remote detection in `remote-dependency-manager.ts`.
- Provider PTY behavior and env passthrough live under `src/main/core/pty/`.
- Provider event hooks and plugins live under `src/main/core/agent-hooks/`.
- Modal definitions are centralized in `src/renderer/app/modal-registry.ts`.
@@ -502,7 +513,7 @@ pnpm run test
- Path aliases are defined in `tsconfig.json` and mirrored in `electron.vite.config.ts`:
`@/*`, `@renderer/*`, `@main/*`, `@shared/*`, and `@root/*`.
- Versioned JSON column schemas are defined in `src/shared/` using
- `defineVersionedSchema()` from `src/shared/lib/versioned-schema.ts` and wired to
+ `defineVersionedSchema()` from `src/shared/lib/versioned-schema/versioned-schema.ts` and wired to
Drizzle via `versionedJsonColumn()` from `src/main/db/versioned-column.ts`.
See `agents/conventions/versioned-schemas.md` for the full guide.
@@ -527,5 +538,5 @@ pnpm run test
- [Database risk notes](agents/risky-areas/database.md)
- [PTY risk notes](agents/risky-areas/pty.md)
- [Updater risk notes](agents/risky-areas/updater.md)
-- [Contributing guide](CONTRIBUTING.md)
+- [Contributing guide](../CONTRIBUTING.md) (repo root)
- [Project README](README.md)
diff --git a/dash/agents/risky-areas/updater.md b/dash/agents/risky-areas/updater.md
index 43ad791f3..a09523399 100644
--- a/dash/agents/risky-areas/updater.md
+++ b/dash/agents/risky-areas/updater.md
@@ -4,14 +4,17 @@
- `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
- `build/`
- `package.json`
- `electron-builder.config.ts`
- `electron-builder.canary.config.ts`
-- `scripts/release/build.ts`
-- `scripts/release/notarize-mac.ts`
-- `scripts/release/rebuild-native.ts`
-- `scripts/release/finalize-release.ts`
+- `.github/workflows/switchdash-release.yml` — the release pipeline (repo root, **not** under `dash/`)
+
+There is no `scripts/release/` directory. Releasing is done by the GitHub Actions
+workflow above, which calls `electron-builder` directly; the packaging, notarization and
+finalize steps are workflow jobs rather than TypeScript entry points.
## Rules
@@ -21,46 +24,63 @@
## Update Feed / Publishing Strategy
-The stable release pipeline publishes to **GitHub Releases** (primary feed) and **Cloudflare R2** (legacy/migration feed) in parallel. Both feeds are served from the same single build.
+The release pipeline publishes to **GitHub Releases** only. The Cloudflare R2 feed that
+ran alongside it during the migration is gone: neither electron-builder config has a
+`generic` publish block, and there is no R2 upload step.
-### Two feeds, one build
+### One feed
-electron-builder emits channel manifests named by the **first** publish provider's `channel`:
+electron-builder emits channel manifests named by the publish provider's `channel`:
-- Stable: `provider: github` has no explicit channel → defaults to `latest` → emits `latest*.yml`.
-- Canary: `provider: github` sets `channel: 'canary'` → emits `canary*.yml`.
+- Stable: `provider: github` (`releaseType: 'release'`) has no explicit channel → defaults to `latest` → emits `latest*.yml`.
+- Canary: `provider: github` (`releaseType: 'draft'`) sets `channel: 'canary'` → emits `canary*.yml`.
-The R2 feed uses different channel names (`v1-stable`, `v1-canary`) that pre-date the GitHub migration. Rather than running a second packaging pass, `scripts/release/build.ts` calls `duplicateChannelManifests()` after the electron-builder step to copy `latest*.yml → v1-stable*.yml` (or `canary*.yml → v1-canary*.yml`). The duplicated manifests are then uploaded to both the GitHub draft release and R2, so every client cohort sees a consistent manifest for its feed.
+The release repo is `sandbox-quantum/switch`, private, so the updater uses
+electron-updater's authenticated GitHub provider.
-### Guard: `upload-r2.ts` hard-fails on missing channel manifest
+### Draft until every platform has uploaded
-`scripts/release/upload-r2.ts` asserts that at least one `${channel}*.yml` file exists before uploading. If `duplicateChannelManifests` did not run or produced no output, the R2 upload step fails immediately with a clear message rather than silently uploading only binaries. A stale channel manifest (frozen at a previous version) combined with newer binaries would cause sha512 checksum failures on client download.
+The workflow does **not** let electron-builder publish (`--publish never`). Instead:
-### Update channels on GitHub
+1. `create-release` opens the GitHub Release as a **draft**. A draft is invisible to
+ 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.
+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.
-The app does **not** override `autoUpdater.channel`; the GitHub provider resolves the channel naturally:
+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.
-- **Stable** (`allowPrerelease=false`): resolves to `latest`, fetches `latest*.yml` from the newest non-prerelease GitHub release.
-- **Canary** (`allowPrerelease=true`): resolves the target release tag from the Atom feed by matching the semver prerelease identifier of the installed version (`canary`) against each entry. Once a `-canary.N` tag is found it fetches `canary*.yml` from that release, as defined by `channel: 'canary'` in `electron-builder.canary.config.ts`.
+### `UPDATE_CHANNEL` is a log label, not a feed selector
-The `UPDATE_CHANNEL` / `v1-stable` / `v1-canary` naming applies **only** to the flat R2 bucket (via the `generic` publish block's `channel`). It is kept as a log label in `update-service.ts` for diagnostics but is not passed to `autoUpdater.channel`.
+`UPDATE_CHANNEL` (`src/shared/app-identity.ts`) is `'v1-stable'` / `'v1-canary'` — naming
+inherited from the retired R2 bucket. It is passed **only** to `log.info` calls in
+`update-service.ts` for diagnostics. It is **not** passed to `autoUpdater.channel` and not
+used to build a feed URL. Do not wire it into feed selection on the assumption that a
+constant named "channel" must be one.
-### R2 decommission path
+### Update channels on GitHub
-R2 uploads continue until all clients are confirmed to have migrated to the GitHub-backed feed. At that point:
+The app does **not** override `autoUpdater.channel`; the GitHub provider resolves the channel naturally:
-1. Remove the `provider: generic` block from `electron-builder.config.ts` and `electron-builder.canary.config.ts`.
-2. Remove the `upload-r2.ts` call and `duplicateChannelManifests` call from `build.ts`.
-3. Decommission the R2 bucket.
+- **Stable** (`allowPrerelease=false`): resolves to `latest`, fetches `latest*.yml` from the newest non-prerelease GitHub release.
+- **Canary** (`allowPrerelease=true`): resolves the target release tag from the Atom feed by matching the semver prerelease identifier of the installed version (`canary`) against each entry. Once a `-canary.N` tag is found it fetches `canary*.yml` from that release, as defined by `channel: 'canary'` in `electron-builder.canary.config.ts`.
- Canary publishes to GitHub as prereleases. `ALLOW_PRERELEASE` in `update-service.ts` is driven by `IS_CANARY` so canary clients accept prerelease versions automatically.
-- The `finalize-release.ts` script runs after all three platform builds complete to flip the draft GitHub release to published. Until that job finishes the release remains a draft and is invisible to electron-updater clients on the GitHub feed.
+- The `publish-release` workflow job runs after all platform builds complete to flip the draft GitHub release to published. Until that job finishes the release remains a draft and is invisible to electron-updater clients.
-## Release Scripts Library Usage
+## Authenticating the updater
-- `scripts/release/build.ts` — uses `electron-builder`'s programmatic `build()` API (no CLI spawn)
-- `scripts/release/rebuild-native.ts` — uses `@electron/rebuild`'s `rebuild()` API (no CLI spawn)
-- `scripts/release/notarize-mac.ts` — uses `@electron/notarize`'s `notarize()` API for DMG submission + auto-staple; system spawns are kept only for `.app` bundle stapling and Gatekeeper verification
+The release repo is private, so a plain feed fetch 404s. `github-token.ts` sources a token
+from the user's `gh` CLI and it is handed to `autoUpdater.setFeedURL(...)` rather than
+exported as `GH_TOKEN`. That is deliberate and worth preserving: switchdash's environment
+is inherited by every child process it spawns — including `gh` itself, which prefers
+`GH_TOKEN` over its keyring — so a token parked there outlives the login it came from and
+shadows the next one until the app restarts.
## Current Notes