ForgeFlow/docs/UPDATING.md

Updating ForgeFlow on Windows

ForgeFlow stores credentials, repository mappings, preferences, deployment profiles, diagnostics and operation history outside the source directory.

Built-in source update

Open Settings → ForgeFlow updates and choose:

1. Check now
2. Download update
3. Apply & restart

The default update source is the configured Gitea instance, repository Jens/ForgeFlow, branch main.

The updater pins the download to the exact remote commit, checks the archive SHA-256, starts an external PowerShell helper and waits for a structured started marker. ForgeFlow closes only after that marker exists. The helper then:

1. waits for the old process to exit;
2. backs up the current source;
3. extracts and validates the requested semantic version;
4. mirrors the incoming source;
5. runs npm ci --no-audit --no-fund when the published release contains package-lock.json, otherwise a pinned direct-dependency npm install;
6. runs npm run check;
7. writes the successful installation result before restart;
8. launches the installed Electron executable directly;
9. persists success, failed or rolled-back state for the next launch.

A failed validation restores the previous source. A successful installation is not rolled back merely because automatic restart fails; start ForgeFlow manually and the persisted result is shown.

Update logs and status files are stored beneath ForgeFlow's local user-data updates folder and exclude the Gitea token.

Packaged Windows updates

ForgeFlow 0.8.2 and newer use authenticated Gitea release assets when running from the installer or portable executable. The updater selects the installer or portable artifact that matches the current installation mode, requires its .sha256 sidecar, validates the Windows executable header and SHA-256 digest, then verifies the digest again immediately before applying it. An external PowerShell helper waits for ForgeFlow to exit, installs or replaces the executable and restarts it.

Publish a verified binary release after pushing its source commit:

npm run dist:win
$env:FORGEFLOW_USER_DATA = "$env:APPDATA\forgeflow"
npm run release:binary

Every platform build finishes by removing ForgeFlow artifacts for older versions from dist. The unpacked application directory and builder diagnostics are kept.

The publisher refuses to upload when local HEAD differs from origin/main. Users on 0.8.1 or older need one manual 0.8.2 installation because those versions deliberately disabled packaged updates.

Publishing a release from Downloads

Extract the complete source ZIP so this file exists:

C:\Users\Jens\Downloads\ForgeFlow-<version>\ForgeFlow\package.json

Run:

cd C:\Users\Jens\Downloads\ForgeFlow-<version>\ForgeFlow
Set-ExecutionPolicy -Scope Process Bypass
.\Publish-ForgeFlow-Release.ps1

The script installs dependencies, runs the complete quality gate, clones git@gitea.itworx.tech:Jens/ForgeFlow.git into a temporary folder, mirrors the validated source without .git, node_modules, dist or release archives, commits it and pushes main. It then compares local HEAD with git ls-remote and fails if Gitea does not report the exact release commit.

Keep the currently installed older ForgeFlow source folder untouched until the built-in updater test is complete.