AIClaw 3.7.15 Brings an Installer Option to Windows Updates

AIClaw v3.7.15 adds a Windows x64 installer (NSIS), checksum verification, and an interactive update flow on top of the ZIP portable package. The core value isn't feature stacking — it's splitting the process into four clear stages: download, verify, launch installer, and complete the upgrade, so users understand the boundaries and responsibilities of each update.

From ZIP Extraction to an Interactive Installer

In the past, updating a desktop app via ZIP meant finding the newly downloaded package, closing the running app, extracting, and replacing the target directory. That's fine for portable distribution, but it becomes repetitive work once releases pick up pace. AIClaw v3.7.15 keeps the ZIP while adding an interactive Windows x64 NSIS installer, and the public release page ships both the installer and a checksum file.

The point of this change is to move updates from "manual file management" to an auditable download-verify-launch chain, reducing the steps where users touch files directly.

NSIS (Nullsoft Scriptable Install System) is an open-source framework for building Windows installers. It describes installation steps, components, shortcuts, and uninstall logic via scripts, producing a single executable installer. electron-builder supports NSIS as one of its Windows targets, and can output either an interactive (wizard UI) or silent (no UI) installer. The reason to choose NSIS over MSI is usually simpler build configuration, more direct integration with the Electron packaging pipeline, and coverage of the vast majority of individual-user scenarios. Microsoft Installer (MSI) is more convenient for Group Policy deployment in enterprise domain environments, but it requires an extra toolchain and stricter component registration. The "interactive" form used here means that install path and confirmation steps are left to the user in the wizard — the app doesn't fill in silent flags on their behalf.

The Four-Step Decision Path of the Update Flow

After the user clicks the update action, the Windows updater runs a fixed sequence in apps/desktop/src/main/updater.ts:

1. Check the latest GitHub Release and confirm a newer version exists.
2. Locate the Windows installer for the corresponding version and download it to a temp directory.
3. Download SHA256SUMS.txt and compare the installer's digest against the named entry.
4. Ask Windows to open the installer; once handoff succeeds, exit AIClaw and let the user complete the install confirmation.

The app does not pass a silent-install flag. Its notion of "success" means the installer has been launched, not that installation is complete. If the user cancels in the wizard, they can still reopen the old version. There's no cross-app-and-installer transactional guarantee, and no automatic rollback mechanism.

The App Should Keep Running When Verification Fails

When the checksum entry is missing or the digest doesn't match, the installer is not opened. A download failure or an OS launch error also leaves AIClaw running. Failure paths clean up the temp download directory and open the releases page so the user can check available downloads themselves.

The updater refuses to install from dev mode. Releases with only a ZIP fall back to the previous "download and open folder" behavior. This fallback exists for compatibility with older release formats, not to bypass checksum checks for installers that already exist. For maintainers, the distinction matters: releases predating installer support still work, while a corrupted installer download is reported explicitly as a failure.

Checksums Are Integrity Checks, and a Trust Boundary Exists

Digest comparison only verifies that the downloaded executable matches the digest provided by the release. It does not independently prove the publisher's identity. The executable and the checksums come from the same distribution channel. The current installer is not Authenticode-signed, so Windows may show an unknown-publisher warning. This implementation neither disables system protections nor equates a checksum match with a publisher signature.

This is worth emphasizing: checksums solve transport integrity, not source authenticity. Users still have to trust the distribution channel themselves.

SHA256SUMS.txt is a common release artifact manifest format, where each line consists of "digest + two spaces + filename," originating from GNU coreutils' sha256sum tool. It was originally used to batch-verify archive files on POSIX systems, and later adopted by many open-source projects to form a two-tier "checksum + signature" defense alongside GPG signatures. AIClaw currently only does the first tier: digest comparison. If the manifest itself is replaced, the comparison still passes, so the real trust anchor is the distribution channel (the GitHub Release page) itself.

Authenticode is Windows' code-signing mechanism, with signing certificates issued by trusted CAs. Signed executables display a publisher name in SmartScreen and UAC prompts, letting users judge the source. An unsigned installer triggers an "unknown publisher" warning, but the system does not block execution. Signing typically requires a paid certificate and build-time key management, so individual projects often skip it in early stages. Note that Authenticode and "whether checksums pass" are independent dimensions: the former answers "who published it," the latter answers "was transmission corrupted."

Package the App First, Then Build the Installer

The installer build script (scripts/package-win-installer.mjs) consumes the Windows app directory produced by the existing packager, reads the app version from it, and passes the prepared directory to electron-builder's NSIS target. The config uses a stable app ID, an assisted wizard, versioned installer file names, disables install-directory selection, and sets deleteAppDataOnUninstall=false. The main process also sets a matching Windows AppUserModelID and preserves the existing user-data app name.

Program replacement and user-data retention are two different things. The installer replaces app files; settings and chats continue to use the existing Electron user-data location, and global app data and memory keep their original home-directory location — the installer doesn't move them into the program folder.

For existing ZIP users, the first migration is manual: download the new setup executable, install it, and use the new shortcut. The old extracted directory is not removed automatically. The old ZIP app's updater won't gain new behavior just because an installer exists on GitHub. Once the new implementation is running, subsequent updates that provide an installer can use this download-launch path. The portable ZIP remains for users who prefer it.

The Electron user-data directory by default lives at %APPDATA%\<appName> and stores settings.json, chat history, caches, and so on; the userData path is determined by the main process via app.setPath or by the product name in the packaging config. Global app data is typically defined under the user's home directory (e.g., ~/.aiclaw) for model files or global memory shared across installations. The installer only replaces program files under <Program Files>\AIClaw, and deleteAppDataOnUninstall=false exists precisely to preserve that user data on uninstall. The Windows AppUserModelID is used for taskbar grouping and notification attribution; the appId in the packaging config must match what the main process sets, otherwise the same app may show up as two icons or have misattributed notifications. package-win-installer.mjs treats the packaging output directory as its input, avoiding duplicate extraction or rebuilds, and keeps the app version number in sync with the installer naming.

Test Host Handoff and Windows Installation Separately

The updater regression tests (scripts/test-updater.ts) mock Electron and network responses, covering valid digest and pre-launch exit ordering, wrong or missing checksums, OS launch failure, ZIP-only fallback, no-update/dev-mode/invalid-tag cases, and Release API failures. These tests verify the updater's decisions, but do not execute the Windows installer.

The native smoke script (scripts/smoke-win-installer.ps1) performs install testing separately on a Windows runner: installing to a temp path containing spaces, checking expected app files, modifying program files to stale fixtures, then reinstalling to verify replacement; it also places sentinel files in two user-data locations and checks them after install, reinstall, and uninstall. The script uses silent flags for automated testing; these flags are never passed by the app's interactive update path. Its replacement check only reinstalls the same build and overwrites modified files — it does not simulate every cross-version migration, nor does it validate every real user database.

The publicly released v3.7.15 release workflow completed successfully, including the Windows installer job. The workflow definition makes the release depend on that job. The release notes also report local checks and six passing updater regression tests. The author verified the tagged tests and the public workflow results, but did not re-run the test suite or perform an independent Windows desktop acceptance test.

The Electron main-process app updater runs in a Node environment and can call shell.openPath directly to open an external installer, but there is no callback between the open action and install completion — the exit code only indicates "whether the installer process launched successfully." This explains why "success" in this context is defined as handoff complete rather than upgrade complete.

Regression tests stub out Electron modules and network requests, asserting that the state machine chooses the correct branch for each input combination; they don't touch real Windows APIs, so they run fast and on any CI platform. Smoke tests are the opposite: they must run on a Windows runner, because they depend on MSI/NSIS replacement semantics, file-locking behavior, and real directories like %APPDATA%. The two complement each other: the former prevents logic regressions, the latter catches environment-specific issues (such as paths with spaces, antivirus interference, or a locked install directory). Using silent flags to drive the smoke script here is precisely to bypass GUI interaction for automated testing — a separate channel from the interactive handoff of the app's update path, and the two must not be conflated.

Key Takeaways

• AIClaw v3.7.15 adds a Windows x64 NSIS installer alongside the ZIP, turning updates from manual file management into a three-step download-verify-launch chain.
• Checksum verification prevents download corruption but doesn't verify publisher identity; the installer is not Authenticode-signed.
• When verification fails, download fails, or launch fails, the app keeps running, cleans the temp directory, and opens the releases page.
• Program replacement and user-data retention are separated; the installer doesn't migrate user settings, chat history, or global data.
• Updater regression tests and native Windows install smoke tests are separate: the former verifies decisions, the latter verifies install behavior.

One-line Summary

AIClaw v3.7.15 adds a Windows NSIS installer, replacing manual ZIP updates with a download-verify-launch chain and clarifying the trust boundary of checksums.

Paragraph Summary

AIClaw v3.7.15 keeps the portable ZIP while adding an interactive Windows x64 NSIS installer, simplifying updates from "download ZIP, manually replace files" to four steps: check the Release, download the installer, compare against SHA256SUMS.txt, and hand off to Windows to launch the installer. The article emphasizes that the app's success criterion is the installer being launched, not installation completing; canceling mid-way still lets users run the old version. Checksums only address transport integrity, not publisher identity, and the installer isn't Authenticode-signed, so Windows may show an unknown-publisher warning. Failure scenarios (mismatched checksums, download failure, launch errors) keep the app running, clean the temp directory, and open the releases page. The installer replaces program files but doesn't migrate user settings, chat history, or global data, so existing ZIP users migrate manually the first time. Testing is split between regression tests for decision logic and smoke tests on a Windows runner for install/uninstall behavior.