iris-context/docs/dev/updater.md

Versioning and updates

Iris has a built-in update notification system designed to be non-intrusive and zero-latency

The update system is designed to keep Iris up to date while staying out of the way. It performs an asynchronous network check when the shell starts and notifies you exactly once per version after you run a command. This prevents redundant notifications and ensures that you only see an update message when a new release is actually available. The system also includes dedicated debugging tools to verify the notification logic without requiring real releases

How it works

1. Background check: every time you open a new terminal, Iris launches a background goroutine to check for updates

   • checks the network at most once every 6 hours to avoid GitHub API rate limiting
   • has a 5 second timeout so it never hangs on a slow or missing network connection
   • if there is no network, it fails silently with zero impact on startup

2. State persistence: state is stored in ~/.iris/update_state.json with two fields:

   • last_check - unix timestamp of the last network check
   • seen_version - the latest version the user was already notified about

3. Smart notification:

   • the notice only appears after you run your first command (triggered by the IRIS_CMD_STOP IPC signal from the shell hook)
   • appears only once per session, never again even if you keep the terminal open
   • if you have already been notified about a specific version, it will not show again until a newer GitHub release tag is detected
   • when iris update is run successfully, the seen_version flag is cleared

Build-time versioning

Iris uses Go ldflags to inject the version string at build time:

go build -ldflags="-X github.com/versenilvis/iris/root.Version=v1.2.0" -o iris main.go

If not provided, the version defaults to dev. The dev version will never trigger an update notification

Commands

• iris version - print the current version of the running binary
• iris update - manually check for and apply the latest release

Debugging and testing

There are two separate things to test: the update command itself, and the in-session notification banner

Test 1: update command

Tests version fetching, comparison and the output message. No full Iris session needed

just build-release v0.0.1
just debug-update v1.99.0

Expected output

--- testing iris update command ---
checking for updates (current: v0.0.1)...
[IRIS] updating v0.0.1 -> v1.99.0
running: curl -sS https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh

[IRIS] restart your terminal to use the new version

Test 2: in-session notification banner

Tests the yellow notice that appears after you run your first command inside a live Iris session. Requires iris.zsh to be active in the inner shell so IRIS_CMD_STOP fires through the IPC pipe

just build-release v0.0.1
just debug-notify v1.99.0

Inside the new session, run any command. Expected output after the command

[IRIS] new version v0.0.1 -> v1.99.0 available, run iris update to upgrade

Environment variables

Variable	Purpose
IRIS_UPDATE_URL	override the GitHub API endpoint with a custom URL (used by debug-update)
IRIS_MOCK_LATEST_VERSION	skip network entirely, resolve to this version immediately (used by debug-notify)

State reset

To force a fresh network check on next launch, delete the state file:

rm ~/.iris/update_state.json

Implementation details

File	Purpose
root/version.go	holds the Version constant, defaults to dev
root/update.go	all update logic: state persistence, network fetch, version compare, commands
root/wrapper.go	wires the background check into the IPC loop, prints the notice on first IRIS_CMD_STOP