Merge pull request #163 from realgarit/realgar/fix-release-flow

fix: repair release flow and recover v3.24.2

Author: realgarit

.github/workflows/build.yml

@@ -61,7 +61,7 @@ jobs:
 
     steps:
     - name: Checkout release commit
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       with:
         # Draft GitHub releases do not create their tag until publication.
         ref: ${{ needs.release-please.outputs.release_sha }}
@@ -80,30 +80,14 @@ jobs:
         fi
 
         VERSION="${RELEASE_TAG#v}"
-        VERSION_FILE="$(tr -d '[:space:]' < version.txt)"
-        if [[ "$VERSION_FILE" != "$VERSION" ]]; then
-          echo "::error::version.txt contains '$VERSION_FILE', expected '$VERSION'."
+        bash scripts/validate-version-sync.sh "$VERSION"
+
+        MANIFEST_VERSION="$(jq -r '."."' .release-please-manifest.json)"
+        if [[ "$MANIFEST_VERSION" != "$VERSION" ]]; then
+          echo "::error::.release-please-manifest.json contains '$MANIFEST_VERSION', expected '$VERSION'."
           exit 1
         fi
 
-        for PROPERTY in Version AssemblyVersion FileVersion; do
-          PROJECT_VERSION="$(sed -n "s:.*<$PROPERTY>\\([^<]*\\)</$PROPERTY>.*:\\1:p" phonedesk.csproj | head -1)"
-          if [[ "$PROPERTY" == "Version" ]]; then
-            # Version must match exactly (SemVer, 3 parts)
-            if [[ "$PROJECT_VERSION" != "$VERSION" ]]; then
-              echo "::error::$PROPERTY is '$PROJECT_VERSION', expected '$VERSION'."
-              exit 1
-            fi
-          else
-            # AssemblyVersion/FileVersion need 4 parts on Windows; accept either 3.21.3 or 3.21.3.0
-            EXPECTED4="${VERSION}.0"
-            if [[ "$PROJECT_VERSION" != "$VERSION" && "$PROJECT_VERSION" != "$EXPECTED4" ]]; then
-              echo "::error::$PROPERTY is '$PROJECT_VERSION', expected '$VERSION' or '$EXPECTED4'."
-              exit 1
-            fi
-          fi
-        done
-
         if [[ "$(git rev-parse HEAD)" != "$RELEASE_SHA" ]]; then
           echo "::error::Checked out commit does not match Release Please SHA '$RELEASE_SHA'."
           exit 1
@@ -138,12 +122,12 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       with:
         ref: ${{ needs.release-please.outputs.release_sha }}
 
     - name: Setup .NET
-      uses: actions/setup-dotnet@v6
+      uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6
       with:
         dotnet-version: '10.0.x'
 
@@ -220,7 +204,7 @@ jobs:
         zip -r ../../dist/phonedesk-linux-x64.zip .
 
     - name: Upload build artifacts
-      uses: actions/upload-artifact@v7
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
       with:
         name: phonedesk-${{ matrix.runtime }}
         path: ./dist/*
@@ -237,7 +221,7 @@ jobs:
     steps:
     - name: Download all artifacts
       # Build jobs upload finished assets (zips / setup exe), so a flat merge is enough.
-      uses: actions/download-artifact@v8
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
       with:
         pattern: phonedesk-*
         path: ./artifacts
@@ -285,7 +269,7 @@ jobs:
     if: needs.release-please.outputs.release_created == 'true'
     steps:
     - name: Checkout tap
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       with:
         repository: realgarit/homebrew-tap
         token: ${{ secrets.PAT_TOKEN }}
@@ -371,14 +355,18 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       with:
         # For PR events, use the head SHA (not the merge ref) to avoid race
         # where the merge ref is deleted before the runner picks up the job.
         ref: ${{ inputs.validate_ref || github.event.pull_request.head.sha || github.ref }}
 
+    - name: Validate version source alignment
+      shell: bash
+      run: bash scripts/validate-version-sync.sh
+
     - name: Setup .NET
-      uses: actions/setup-dotnet@v6
+      uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6
       with:
         dotnet-version: '10.0.x'
 

.github/workflows/module-compatibility.yml

@@ -19,10 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v6
+        uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6
         with:
           dotnet-version: '10.0.x'
 
@@ -84,9 +84,9 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git checkout -b "$BRANCH"
           git add scripts/module-versions.json
-          git commit -m "chore: bump bundled PowerShell module versions"
+          git commit -m "fix(deps): bump bundled PowerShell module versions"
           git push origin "$BRANCH"
-          gh pr create --title "chore: bump bundled PowerShell module versions" \
+          gh pr create --title "fix(deps): bump bundled PowerShell module versions" \
             --body "$(cat <<EOF
           Weekly module compatibility check found newer versions on the PowerShell Gallery.
 

AGENTS.md

@@ -86,3 +86,4 @@ Always: **branch → commit → push + open PR → CI green → merge (merge com
 - 2026-07-21 — **Microsoft Store**: EXE-app product `53a8f446-bbf3-4c01-9156-3ef5b44aaf57` in Partner Center. Package URLs must not redirect → installers copied to `gh-pages` branch `store/<version>/`, served from `https://realgarit.github.io/phonedesk/...`; listing screenshots generated via `GENERATE_SCREENSHOTS=1 SCREENSHOT_FRAMELESS=1`. Store's automated silent-install/ARP checks can't see per-user (HKCU) installs — those warnings are expected; verify manually. Pending: automate gh-pages copy + Store submission API in build.yml; code-signing cert (Azure Trusted/Artifact Signing unavailable to Swiss individuals — classic CA needed, SSL.com eSigner favored); Kaspersky Allowlist submission after signing.
 - 2026-07-21 — Open PR #148 (module-compatibility bot) predates the rebrand and needs a rebase onto renamed paths before merge.
 - 2026-07-23 — MS Store cert 10.1.1.1 also rejected the "PhoneDesk for Microsoft Teams" Store-name form: the Store product-name field may not contain any Microsoft product name at all. Listing changed to bare "PhoneDesk" and resubmitted; "for Microsoft Teams" remains only in the Store description/keywords and in-app branding.
+- 2026-08-10 — **Bundled-module update #161 and version bump #162 merged**: `scripts/module-versions.json` now pins the five Microsoft.Graph modules to `2.39.0`; app version sources are `3.24.2`. Both PRs passed the full platform/review gates and the local suite ran 541 tests. Live release verification found no `v3.24.2`: release-please ignored the merged `chore:` commits as non-user-facing, and `version.txt` remains `3.24.0`; repair the release trigger/version-file alignment before claiming delivery.

docs/release-please-setup.md

@@ -2,83 +2,103 @@
 
 This project uses [release-please](https://github.com/googleapis/release-please) (via the
 `googleapis/release-please-action` GitHub Action) to automate versioning and release
-management. Every push to `main` triggers RP to evaluate conventional commit messages
-since the last release and propose a release PR.
+management. Every push to `main` triggers release-please to evaluate Conventional Commit
+messages since the last release and propose a release PR.
 
-## Version pinning (fixed at v4)
+## Version pinning
 
-RP is pinned to **v4** of `googleapis/release-please-action` via an explicit commit SHA:
+The workflow pins `googleapis/release-please-action` to the v5.0.0 commit SHA:
 
-```
-uses: googleapis/release-please-action@8b8fd2cc23b2e18957157a9d923d75aa0c6f6ad5 # v4
+```yaml
+uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
 ```
 
-We deliberately do **not** use a floating tag (`v4`) or a version range (`>=4`). This
-prevents Dependabot or GitHub's own action resolver from silently upgrading the action to
-v5, which would trigger phantom major-version bumps (e.g. 3.x → 4.0.0) because v5 uses a
-different release-please CLI that re-evaluates the entire commit history.
+The explicit SHA prevents an action-tag update from changing release behavior
+unexpectedly. The root-level `last-release-sha` in `release-please-config.json` anchors
+release-please after the v3.21.5 release commit so old breaking-change footers cannot
+recreate the retired phantom v4.0.0 release.
 
-## Preventing phantom major-version bumps
+## Commit types and one-time recovery
 
-The primary protection against phantom bumps (e.g. 3.x → 4.0.0) is **pinning the
-action to a v4 commit SHA** (see above). RP v5 re-evaluates the entire commit history
-and may propose a major bump based on old breaking-change commits.
+Release-please treats user-facing Conventional Commits such as `fix`, `feat`, and
+`deps` as releaseable. Routine `chore` commits are not releaseable. The scheduled module
+compatibility workflow therefore generates:
 
-Beyond that, RP is **self-managing**: it tracks `last-release-sha` internally and
-updates it automatically when a release is published. No manual SHA management is
-needed under normal operation.
+```
+fix(deps): bump bundled PowerShell module versions
+```
 
-Do NOT add `release-as` or `last-release-sha` to `release-please-config.json` unless
-you need a one-time override (e.g. bootstrapping a new release track). These manually
-lock the version and prevent RP from evaluating new commits correctly.
+For a one-time recovery, a commit body may contain the exact footer:
 
-## Four-digit version fields for Windows
+```
+Release-As: 3.24.2
+```
 
-The .NET project uses these MSBuild properties in `phonedesk.csproj`:
+Use that footer only to recover a known pending release. Do not add a persistent
+`release-as` override to `release-please-config.json`; it would lock normal version
+calculation.
 
-```xml
-<Version>3.21.3</Version>            <!-- SemVer — must match RP tag exactly -->
-<AssemblyVersion>3.21.3.0</AssemblyVersion>   <!-- 4-part for Windows compatibility -->
-<FileVersion>3.21.3.0</FileVersion>           <!-- 4-part for Windows compatibility -->
-```
+## Application version sources
 
-- **`<Version>`** is 3-part SemVer and must match the release-please tag (e.g. `v3.21.3`).
-- **`<AssemblyVersion>` / `<FileVersion>`** use 4-part versions (e.g. `3.21.3.0`) because
-  Windows requires four digits. The CI validation in `build.yml` accepts either `X.Y.Z` or
-  `X.Y.Z.0` for these properties (see the `validate-release` job).
+The application-facing sources must agree on the same three-part version:
+
+- `version.txt`
+- `phonedesk.csproj` `<Version>`
+- `app.manifest`'s four-part `assemblyIdentity` version
+- `src/PhoneDesk.Domain/ConstantsService.cs`
+
+`phonedesk.csproj` keeps four-part `<AssemblyVersion>` and `<FileVersion>` values for
+Windows compatibility. Run `bash scripts/validate-version-sync.sh` to check these
+sources. Both `scripts/bump-version.sh` and `scripts/bump-version.ps1` update
+`version.txt` along with the other application sources.
+
+`.release-please-manifest.json` is release-please-managed state. It may trail the
+application sources while a release is waiting to be proposed, but
+`validate-release` requires it to match the release tag.
 
 ## Key files
 
 | File | Purpose |
 |------|---------|
-| `.github/workflows/build.yml` | CI/CD pipeline: RP, validation, build, publish, Homebrew |
-| `release-please-config.json` | RP config: release-type, extra-files, draft mode |
-| `.release-please-manifest.json` | Current package version (auto-managed by RP) |
-| `version.txt` | Human-readable version (must match RP version) |
+| `.github/workflows/build.yml` | CI/CD pipeline: release-please, validation, build, publish, Homebrew |
+| `.github/workflows/module-compatibility.yml` | Weekly module pin check and releaseable dependency PR |
+| `release-please-config.json` | Release-please config: release type, anchor, extra files, draft mode |
+| `.release-please-manifest.json` | Release-please-managed package version |
+| `version.txt` | Application version source |
+| `scripts/validate-version-sync.sh` | Cross-platform application version-source guard |
 | `phonedesk.csproj` | Project `<Version>`, `<AssemblyVersion>`, `<FileVersion>` |
 
 ## What happens on a push to `main`
 
-1. **`release-please` job**: RP evaluates commits since `last-release-sha`, creates or
-   updates a release PR (branch: `release-please--branches--main`).
-2. **PR validation**: The `pr-validate` job builds + tests the PR across all runtimes
-   (Windows, macOS Intel, macOS ARM, Linux).
-3. **When the release PR is merged**: RP creates a Git tag and a draft GitHub release,
-   then the full `build` → `upload-release-assets` → `bump-homebrew-cask` pipeline runs.
+1. **`release-please` job**: release-please evaluates commits after
+   `last-release-sha` and creates or updates a release PR
+   (branch: `release-please--branches--main`).
+2. **PR validation**: the `pr-validate` job checks version-source alignment, then
+   builds and tests the PR across Windows, macOS Intel, macOS ARM, and Linux.
+3. **When the release PR is merged**: release-please creates the Git tag and draft
+   GitHub release, then `build` → `upload-release-assets` → `bump-homebrew-cask` runs.
 
 ## Troubleshooting
 
-### RP keeps creating duplicate or phantom release PRs
-- Verify `release-please-config.json` has `"last-release-sha"` pointing to the
-  **exact commit** of the most recent release tag (under the `packages."."` key).
-- Verify the action is pinned to a **v4 commit SHA**, not a floating `v4` tag.
-- Delete stale RP branches (`release-please--branches--main-*`) and re-run.
+### Release-please does not create a release PR
 
-### Validate-release fails with "Version is not a stable semantic version"
-- Ensure the release tag matches `vX.Y.Z` format (no pre-release suffixes, no fourth
-  digit).
-- Check that `<Version>` in `phonedesk.csproj` matches the tag exactly (3 parts).
+- Check that the merged change uses a releaseable type such as `fix`, `feat`, or
+  `fix(deps)`, rather than an ordinary `chore`.
+- For a known pending version, use a one-time `Release-As: X.Y.Z` footer.
+- Verify `release-please-config.json` has the root-level `last-release-sha` pointing to
+  the intended release anchor.
+- Delete stale release-please branches (`release-please--branches--main-*`) only after
+  inspecting their PR and branch state.
+
+### Validate-release fails with a version mismatch
+
+- Ensure the release tag matches `vX.Y.Z` format with no pre-release suffix or fourth
+  digit.
+- Run `bash scripts/validate-version-sync.sh X.Y.Z` locally.
+- Check that `.release-please-manifest.json` contains the same three-part version as the
+  release tag.
 
 ### Windows builds fail on version mismatch
-- `<AssemblyVersion>` and `<FileVersion>` must be 4-part (e.g. `3.21.3.0`). Windows
-  does not accept 3-part assembly versions.
+
+- `<AssemblyVersion>` and `<FileVersion>` must be four-part values such as `3.21.3.0`.
+- `<Version>` remains three-part and must match the release tag exactly.