ForgeFlow/docs/RELEASE_AUDIT_0.6.0.md

ForgeFlow 0.6.0 release audit

Scope

This audit covers the source release intended for publication to Jens/ForgeFlow and subsequent installation through ForgeFlow's built-in source updater.

Reviewed areas:

• local Git discovery, status, staging, commit, push, fetch and fast-forward;
• large Windows path selections and deleted/renamed files;
• stale Git lock diagnosis, conservative repair and automatic retry;
• divergence recovery with a safety branch;
• Gitea repository and Actions integration;
• SSH host identity, Unraid-to-Gitea preflight and exact-SHA deployment;
• Docker Compose identity normalization while preserving visible container names;
• DockerMan WebUI, icon and shell labels, XML fallback and cache refresh;
• interrupted/stale deployment reconciliation;
• renderer viewport behavior and guided troubleshooting;
• diagnostics redaction and support bundles;
• release publication and built-in source-update lifecycle.

Regression coverage

The automated suite contains 99 passing tests, including real temporary Git repositories and bare remotes. High-risk regressions covered directly include:

• staged and unstaged deletions;
• renamed files;
• a local commit followed by a failed push;
• 850 long selected paths transported through NUL-delimited stdin;
• stale HEAD.lock removal while excluding Git object/LFS storage;
• backup-before-reset repair of a diverged branch;
• exact remote-SHA checks;
• background SSH deployment completion without a stuck operation;
• startup/manual reconciliation of live Unraid state;
• lowercase-safe Compose project/service/image identities with visible Portfolio casing;
• DockerMan labels, built-in icon upload, XML fallback and cache invalidation;
• source-updater STARTED handshake, result acknowledgement, direct Electron restart and rollback state.

Product behavior added for the reported incidents

• Git mutations are serialized per repository.
• A lock failure triggers a safe diagnosis and one automatic repair/retry when no active Git process is detected.
• Git Tools provides personalized scan, lock repair, origin repair, fast-forward, push and safety-branch divergence recovery actions.
• Successful SSH deployments become terminal before the secondary server refresh, preventing a live container from leaving ForgeFlow in deployment mode.
• ForgeFlow refreshes configured server truth after startup and through the combined refresh action.
• A healthy live SHA equal to local/Gitea is not offered for deployment again.
• Running containers missing DockerMan metadata can be repaired individually or in one batch from Deployments.
• Built-in/uploaded icons are placed in persistent DockerMan storage, referenced through a file:/// label, written into a user template and copied into known icon caches.
• WebUI uses the Unraid label placeholders based on the configured host port and path.
• Update publication creates and publishes package-lock.json; the updater uses npm ci when it is present.
• Update success is persisted before restart, and restart invokes Electron directly rather than relying on a detached npm process.

Static and packaging checks

• every JavaScript/CJS/MJS source file passes node --check;
• required source, branding, documentation, updater and deployment files are present;
• direct dependency versions are pinned;
• renderer privileged actions remain behind the preload/IPC boundary;
• the PowerShell update helper starts with param(, has no UTF-8 BOM and contains lifecycle state before shutdown/restart;
• release archives exclude .git, node_modules, dist, update downloads and generated ZIPs;
• the generated source manifest records SHA-256 and size for every distributed source file.

Remaining live acceptance step

The automated environment cannot execute Windows PowerShell 5.1 or connect to the user's private Gitea/Unraid services. The final live acceptance is therefore deliberately the requested workflow:

1. publish the release from an extracted Downloads folder;
2. leave the installed older source at C:\Projects\ForgeFlow untouched;
3. open that older ForgeFlow;
4. use Settings → ForgeFlow updates → Check now → Download update → Apply & restart;
5. confirm the restarted application reports version 0.6.0 and displays the persisted success result.

A failed handoff must keep the old app open. A failed validation must restore the previous source. A successful installation remains installed even when only automatic restart fails.