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.

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.