CodeNomad/dev-docs/TAURI_UPDATER.md

# Tauri updates and Linux AppImage distribution

## Installation contract

The native Get Updates menu, the required-upgrade notification and the preview
release notification share `stores/desktop-updates.ts`. A check offers an
explicit **Install and restart** action. The renderer supplies only the saved
update feed and later the version it accepted; Rust selects the release, retains
the checked native `Update` and owns every URL and the verification key.
Each new check or install replaces the previous update notification so stale
install offers do not remain actionable after a failure or changed check result.

Update feeds follow the server notification rules (`server.updateFeed`, else
derived from the installed build label), implemented natively in
`update_releases.rs` from the GitHub releases list:

| Feed | Offered release |
| --- | --- |
| `stable` | GitHub's latest final release (`/releases/latest`, never displaced by prereleases) when it has a `latest.json` and a higher version |
| `preview` | Newest publication of any kind (dev prerelease or release) with a `latest.json`, newer by publication than the installed release |

Preview labels reuse their base version, so SemVer alone can rank a newer
preview below an older one; publication order decides, and builds unknown to
GitHub fall back to version order as on the server. Only the selected release's
manifest is fetched, and it must announce exactly the selected version. Releases
without a manifest (still building, partially failed or older than the updater)
are never offered, so a release in progress cannot break checks.

The native menu emits `menu:action` to the focused local webview only, and the
renderer listens on its own webview: untargeted Tauri listeners receive every
window's events. When Preferences or a remote window is focused, or no local
window remains, Get Updates opens the release page. Renderer fallbacks use the
saved feed (stable: the latest release; preview, or a feed that could not be
read: the full releases list, which contains every offered release). The
native fallback and About link cannot read the saved feed and derive it from
the installed build label.

When a notification's check finds nothing installable, it opens that
notification's release page rather than reporting the application as current.

Supported installed formats:

| Target | Updater payload |
| --- | --- |
| Windows x64 NSIS | Signed `.exe` |
| macOS x64 | Signed `.app.tar.gz` |
| macOS arm64 | Signed `.app.tar.gz` |
| Linux x64 AppImage | Signed `.AppImage` |

Debian/RPM packages, loose Windows executables and builds without an embedded
public key open the release page. Linux requires both the native AppImage bundle
marker and a nonempty `APPIMAGE` path; `APPRUN` alone is insufficient.

`desktop_updater.rs` authorizes native callers against local application origins
and serializes checks/downloads across windows. A check while another window
checks or installs returns `busy`, shown as information rather than a failure
(a notification still opens its release page). Only the three guarded application
commands (check, install, take failure) are granted to local webviews; never
grant updater/process plugin permissions to previews, remote windows or
renderers generally.

The plugin verifies the complete download before shutdown admission. A prepared
installer and restart intent enter the shutdown coordinator under one lock.
Every renderer must flush and the owned CodeNomad backend must stop before
installation. A timeout or cleanup failure discards the pending installer; a
late acknowledgement or later ordinary quit cannot replay it. Windows logout
discards a waiting update. Installation never stops the shared OpenCode daemon.

On macOS/Linux, successful installation follows the normal native restart. On
Windows, the NSIS installer performs relaunch and the plugin exits. The vendored
2.12.0 plugin runs its exit callback only after a successful `ShellExecuteW`, so
a refused launch keeps client-state persistence ownership. On an installation
error, the application restores its owned backend without replaying installation.
That recovery reloads every window, so failures are recorded natively with the
webview whose install was accepted. That webview's document takes and reports
it, including after a reload; once that webview is closed, any local document
takes it. Download failures are recorded and emitted too, since the caller may
reload or close during a long download; the live caller reports each failure
once, whether its rejected request or the event arrives first.
Failures without a reload (flush timeout, cleanup failure, refused backend
recovery) are also emitted to live documents; another document merely checking
cannot take them.
Notification history retains install actions, so an offer from an earlier check
starts a fresh check instead of installing.

The loading, sign-in (`/login`, `/auth/*`) and pairing documents have no menu
listener: Get Updates opens the release page while the focused local window
shows one of them. Every other server path serves the application, whose
listener registers when it mounts.
See `packages/tauri-app/vendor/README.md` for provenance.

## Build and publication

`configure-updater.mjs` writes a Tauri V2 `plugins.updater` entry and
`bundle.createUpdaterArtifacts: true` when `TAURI_UPDATER_PUBKEY` contains a
minisign public key, with `requireSignedVersion`: the manifest itself is
unsigned, so the signed trusted comment must carry the announced version and an
older signed artifact cannot be relabelled. It configures no endpoint; the
application selects the manifest per feed. Absent keys remove updater
configuration and explicitly disable artifact signing. The native host registers
the plugin only when that configuration exists; the plugin rejects a missing
configuration during initialization, before any check.

Release and dev prerelease uploads use these repository secrets in all four
platform jobs:

- `TAURI_UPDATER_PUBKEY` (job environment; public)
- `TAURI_SIGNING_PRIVATE_KEY` and `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` (only the
  `tauri build` step, never dependency installation or upload steps). Prebuild
  runs earlier without them; `src-tauri/tauri.prebuilt.conf.json` replaces the
  `beforeBuildCommand` hook so JavaScript builds do not rerun with the key.
  Cargo build scripts inside `tauri build` still run in that environment.

PR builds receive none of these secrets. Never embed a test public key in a
production release.

`updater-artifacts.mjs stage` finds exactly one native updater payload, verifies
its minisign data and trusted-comment signatures, requires the trusted comment
to record the release version, copies it to the final release asset name, and
writes a per-platform receipt. The receipt contains the verified signature, the
public key fingerprint and the payload digest, never private key material. The
signature is published only inside `latest.json`, which is where the updater
reads it; staging removes any separate `.sig` asset from a rebuilt tag.

The final publication job waits for all four platform jobs, merges their receipts
and checks the uploaded GitHub asset digests. Missing/duplicate targets, mixed
versions or keys, partial signing and missing or changed payloads fail
publication. Only then does it generate and upload that release's `latest.json`;
stable releases and dev prereleases each carry their own manifest. Receipt
artifacts and the publication job run only for tagged upload builds. PR builds
are unsigned: staging only records an unsigned receipt, and signature/manifest
logic is covered there by the script tests. Before a
platform replaces its signed payload on a rebuilt tag, staging deletes any
existing `latest.json`, so no published manifest pairs new bytes with an old
signature; until publication succeeds, the release is simply not installable.

Downloads have connect (30 s) and read-stall (60 s) limits but no total limit,
so slow connections can still fetch large installers. Fully unsigned builds
produce no update manifest. The release matrix has no Linux arm64 target.

The Linux build requests only `appimage`, with verbose linuxdeploy diagnostics;
the Linux deb is the Electron build. The AppImage carries only Tauri's generated
`CodeNomad.desktop`: Tauri runs linuxdeploy without a desktop-file argument, so
linuxdeploy deploys whichever entry it finds first in `usr/share/applications`.
Keep the hidden reverse-DNS alias entry (`NoDisplay=true`, deb/rpm only) out of
`bundle.linux.appimage.files`; packaging rejects an image with more than one root
desktop entry. The Windows NSIS installer is published
directly as the download and updater payload, without a ZIP wrapper.
The CLI minimum is 2.11.5, the first release that records the app version in
updater signatures' trusted comments; `requireSignedVersion` and publication's
signed-version gate depend on it.

Linux desktop resources omit msgpackr's musl-only native modules. The official
bundled Node runtime is glibc-based; linuxdeploy otherwise runs `ldd` over the
unusable musl ELF and aborts. For local rebuilds after a failed packaging run, remove the generated
`target/release/bundle/appimage` and `target/release/bundle/appimage_deb` staging
directories: the latter can retain removed resources between bundle attempts.

The display and GPU stack comes from the host. The Linux job's
`APPIMAGE_HOST_LIBRARIES` (`libwayland-*`, `libxkbcommon`, `libxcb*`, `libX11*`,
`libXau`, `libXdmcp`, EGL/GL/gbm/drm) reaches linuxdeploy as
`LINUXDEPLOY_EXCLUDED_LIBRARIES`, on top of the excludelist of Tauri CLI 2.12.1
or later. A build-runner copy on AppRun's library path makes Mesa's EGL fail on
newer distributions (an Ubuntu 24.04 `libwayland-client` with Mesa 26), and
WebKit's window then stays black.

The AppRun hook leaves `GDK_BACKEND` to the session. Unless it is set,
`appimage_environment.rs` makes CodeNomad's own GTK prefer X11 (XWayland) and
fall back to Wayland without an X server (`gdk_set_allowed_backends`, on every
Linux build), because the F11 fullscreen shortcut is an X11 key grab; child
processes keep the session's choice. The hook also points GTK, GIO and GSettings
at modules inside the mount (`GIO_MODULE_DIR`, `GTK_PATH`, a prefixed
`XDG_DATA_DIRS`, ...). The backend, and through it the shared OpenCode service,
the editors CodeNomad opens and link handlers outlive the mount, so they start
without those mount paths and outside the mount. Links open
through `external_open.rs`, including the renderer's `open_external_url`
command; the windows hold no opener plugin permission that would bypass it, and
the plugin's injected click handler is off: `lib/native/external-link-clicks.ts`
opens anchors that ask for a new window (`target="_blank"`, Ctrl or Shift)
through `openExternalUrl` instead, in the application and Preferences windows
and in each document a trusted same-origin SideCar frame loads; opaque preview
and panel-extension frames get no opener.

Verification extracts via an absolute artifact path, checks `AppRun` and
`usr/bin/codenomad-tauri`, rejects an image that bundles those host libraries,
smoke-tests bundled Node/server/UI resources, resolves ELF dependencies against
bundled library directories and reports the binary's glibc floor.

The AppImage runtime unmounts the bundle as soon as the main process exits, while
WebKit's helper processes started from it can outlive that process briefly; a
helper that then touches the vanished mount dies with SIGBUS and the desktop
reports a crash. On `RunEvent::Exit`, including updater restarts, the AppImage
host therefore stops its child processes that still run from the mount
(`appimage_exit.rs`): each is pinned with a pidfd and checked again as our child
running from the mount, then receives SIGTERM, and SIGKILL if it has not exited
after 1.5 s; waiting for exits stops after two seconds in total. Children running
from elsewhere, such as the shared OpenCode service, keep running.

## Validation

- Node tests exercise configuration, the four payload formats, manifest
  completeness, key/asset mismatch, payload/trusted-comment tampering and the
  signed release version.
- `update_releases.rs` tests feed resolution, stable/preview selection,
  same-day previews, publication order, drafts and repository-bound URLs.
- `desktop_updater_tests.rs` downloads a CLI-signed public-only fixture through
  the real updater plugin and rejects modified bytes without invoking installers.
  Its insecure HTTP exception exists only in the loopback mock application's config.
- Shutdown regressions verify all-window flushing, cancellation, atomic restart
  admission, conflict with an existing quit and Windows logout.
- The vendored Windows launch regression checks success-only ownership release.
- On Linux, `appimage_exit.rs` tests stop a child running from a temporary
  mount while sparing one running elsewhere; `appimage_environment.rs` tests drop
  mount entries from path lists and keep host values. A real AppImage must quit without
  leaving WebKit helpers or a crash report in `/var/crash`.
- Browser tests exercise the real update store and toast actions, explicit install,
  duplicate gestures, failure recovery (including after a reload), feed
  forwarding and unsigned/Electron/remote fallback.

Commands (from the checkout, unless noted):

```text
node --test packages/tauri-app/scripts/configure-updater.test.mjs packages/tauri-app/scripts/updater-artifacts.test.mjs
npm run typecheck --workspace @codenomad/ui
cargo test --manifest-path packages/tauri-app/src-tauri/Cargo.toml --locked
# From packages/tauri-app on Windows:
cargo test --locked -p tauri-plugin-updater windows_launch_tests
# From packages/ui:
node --import tsx --test tests/browser/desktop-updates.test.ts
```

Signed install/relaunch trials on real artifacts are also required: track
Windows, Linux and macOS trials in the PR; macOS guest access and Apple Silicon
hardware are required for their respective real-device evidence.

## Agent conventions

- The update feed (`server.updateFeed`: `stable`/`preview`, chosen in Settings → Info → Updates) only selects offered releases. It is read on every refresh in `releases/dev-release-monitor.ts`, never from `CODENOMAD_UPDATE_CHANNEL`, and must not touch desktop data scopes, singletons, backends or OpenCode state. Preview offers use publication order (dev builds carry the previous release number) and, like the native updater, consider only releases whose complete `latest.json` exists: release creation precedes the builds, and the manifest is uploaded after every platform build, so a notification is never shown before the release is installable. When the installed release is older than the fetched page, the server looks it up by tag before falling back to version order, and Settings → Info never substitutes a SemVer-ranked stable release on the preview feed. The native Tauri updater follows the same feed (`update_releases.rs`); Electron, remote, unsigned and unsupported installations open the release page.