ForgeFlow-Public/docs/UPDATING.md

Updating ForgeFlow on Windows

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

Source checkouts

Integrated source replacement is disabled until source archives are covered by the same independent publisher signature as packaged releases. A server-provided commit SHA and a checksum calculated from the downloaded archive do not independently authenticate its publisher, while dependency installation can execute package lifecycle scripts.

Update a source checkout through Git instead:

1. fetch the configured upstream;
2. review the exact commit and release notes;
3. switch to the intended release commit or tag;
4. run npm ci --ignore-scripts and review the dependency lifecycle allowlist;
5. run npm run check before starting ForgeFlow.

The in-app updater remains available for signed packaged Windows releases. Version 0.10.16 migrates the default endpoint from Jens/ForgeFlow to Jens/ForgeFlow-Public after a bridge release from the legacy repository. A separately configured update repository is preserved.

Packaged Windows updates

ForgeFlow uses authenticated Gitea release assets when running from the installer or portable executable. The updater selects the artifact that matches the current installation mode and requires its .sha256 sidecar. From version 0.10.13 onward it also requires an Ed25519-signed release manifest. The embedded public key verifies that manifest before ForgeFlow trusts the artifact name, byte length, exact source commit or SHA-256 digest. The digest is checked again immediately before applying the update.

A version bump in the curated ForgeFlow-Public source starts the Windows quality, build, signing and release workflow. It publishes eight required assets:

• ForgeFlow-Setup-<version>-win-x64.exe
• ForgeFlow-Setup-<version>-win-x64.exe.sha256
• ForgeFlow-Portable-<version>-win-x64.exe
• ForgeFlow-Portable-<version>-win-x64.exe.sha256
• ForgeFlow-<version>-provenance.json
• ForgeFlow-<version>-sbom.cdx.json
• ForgeFlow-<version>-release-manifest.json
• ForgeFlow-<version>-release-manifest.json.sig

The release workflow uses the same Ed25519 private key that signed the legacy releases, stored as a repository-scoped Gitea Actions secret. Only the public key is committed. npm run signing:setup remains available for a local recovery build; do not generate a replacement key for existing installations. Authenticode can still be added separately for Windows reputation.

The reviewed source sync runs for every merge to the private canonical repository. Source-only changes do not produce another Windows release. workflow_dispatch can retry a failed binary publication for the current public commit.

When the source was already pushed without a binary release, run the recovery publisher from Windows:

Set-ExecutionPolicy -Scope Process Bypass
.\Publish-Missing-Binary-Release.ps1 -ExpectedVersion 0.9.1

The recovery script clones the current Gitea branch into a temporary directory, verifies the exact branch commit, runs the complete quality gate, builds both Windows artifacts and creates or repairs the matching Gitea release. It uses the encrypted Gitea token already stored by ForgeFlow.

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

The binary publisher refuses to upload when local HEAD differs from the configured Gitea branch. ForgeFlow 0.8.9 and 0.9.0 queried Gitea attachment metadata as though it were the executable. Those versions require one manual 0.9.1 installer run. From 0.9.1 onward, the updater follows the release asset browser download URL and in-app updates work normally.

Publishing a release from Downloads

Extract the complete source ZIP so this file exists:

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

Run:

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

The manual script is a recovery path for an extracted, reviewed ForgeFlow-Public source export. It installs dependencies, runs the quality gate, verifies the exact published source commit, builds the Windows artifacts and uploads the signed release evidence. Publication fails when the source commit, publisher signature or required assets cannot be verified. An already published version is immutable; use a new version for later source changes.

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