OneCAD-Simulation/docs/updates.md

Updates

FieldCraft checks for new releases, verifies them and installs them itself, with your consent at each step. The code is crates/update (fieldcraft-update); the window's side is crates/ui-egui/src/updates.rs, the desktop app's apps/fieldcraft/src/update.rs.

Checking

The app asks the GitHub Releases API for the latest published release (GET https://api.github.com/repos/tangency-labs/fieldcraft/releases/latest; drafts and pre-releases are never offered) and compares its version with the running one (Semantic Versioning order).

• At start-up, at most once a day, when Check for updates automatically is on (the default). It is shown with the first run's question and in Help › Settings… › Updates. Off means no request at all. A failed automatic check is silent (it goes to the log). Runs driven by automation (--control) and CI never check automatically.
• Help › Check for Updates asks now, and says when FieldCraft is up to date or why the check failed.
• Agents and scripts: the app.update.check command (in the app, and through MCP connected to it) and fieldcraft-cli update --check reply with current, latest, newer, url (the release page), published, signed and asset (the file this install would download; null when it cannot update itself). They only report.

The request carries the FieldCraft version in its User-Agent; GitHub sees the request's IP address, as with any download. Nothing else is sent (privacy.md).

A newer release shows a notice in the status bar: FieldCraft 0.5.9 is available — What's new · Install · Skip. What's new opens the release page; Skip stops offering that version (Settings can offer it again).

Verifying

Every release carries SHA256SUMS.txt and, signed with the FieldCraft release key, SHA256SUMS.txt.minisig (Ed25519 in minisign's format; the public key is built into the app, fieldcraft_update::PUBLIC_KEY, and printed in releasing.md). Installing:

1. downloads the list and its signature, and refuses unless the signature is the release key's;
2. downloads the asset for this install and refuses unless its SHA-256 is the one the list gives;
3. on macOS, refuses an app that fails codesign --verify --deep --strict, is not io.github.jyviko.fieldcraft, or is rejected by Gatekeeper (spctl) when the installed app is accepted.

A release without a signature cannot be installed from the app: Install opens its page instead. A development build (run from target/) checks but never installs.

Installing

Install downloads and verifies in the background, unpacks the release beside the installed copy (.fieldcraft-update-<version>, so the swap is a rename on one file system), then asks to restart. Restart Now saves or asks about unsaved changes first, as opening another model does; the window closes, the autosave is closed, the swap is made and the new version starts. Later installs when you quit. A failed swap puts the previous version back; a staging folder left behind is removed at the next start.

Installed as	Asset	Swap
FieldCraft.app (macOS)	fieldcraft-<v>-macos-universal.dmg	the bundle is replaced, then opened
fieldcraft-cli (macOS)	fieldcraft-cli-<v>-macos-universal.zip	the binary is replaced
A Windows folder	fieldcraft-<v>-windows-x64.zip	each file is replaced (a running .exe is renamed away, never overwritten); the app restarts
An AppImage	fieldcraft-<v>-linux-x86_64.AppImage	the file is replaced and started
A tar.gz folder	fieldcraft-<v>-linux-x86_64.tar.gz	the folder is replaced; when its parent is not writable the app says so and links the download
.deb / .rpm	fieldcraft_<v>_amd64.deb / fieldcraft-<v>.x86_64.rpm	never replaced by the app: the verified package is downloaded to the app's data folder (updates/), and the app offers Open with Installer and the sudo apt install … / sudo dnf install … command

Help › Reinstall FieldCraft… downloads and verifies the running version again and swaps it in the same way, to repair a damaged install.

fieldcraft-cli update --install does the same from the command line for the install the CLI belongs to (the tar.gz folder or Windows folder it is in, or the macOS CLI binary), without restarting anything; for .deb/.rpm it prints the package manager command.

The web app

The browser build has no downloads to install: every half hour the page fetches its own address past the browser's cache, and when the deployed page loads another build than the running one (Trunk names each build's files by their content hash), the status bar offers Reload to update. Reloading with unsaved changes asks first, as closing the page does.

Testing

FIELDCRAFT_UPDATE_HOST replaces https://api.github.com with another server, and allows plain http for it. It is for tests against a local server only (fieldcraft_update::mock::Server, behind the crate's mock feature, plays the Releases API); with it set, the app also checks automatically in automation runs, so the notice can be looked at:

FIELDCRAFT_UPDATE_HOST=http://127.0.0.1:8899 fieldcraft-cli update --check

The tests cover version order, the daily schedule and no request when checks are off, asset selection and the swap plan for every install kind, a checksum mismatch and a missing or foreign signature refused (without downloading the asset), archives that try to write outside their folder, undoing a failed swap, and the CLI against a local server. They never replace a running program.