fix(release): round-2 mutator fixes discovered in rel-820 cut first exercise (openemr#12731)

Fixes 5 bugs surfaced by today's rel-820 cut — the first end-to-end
production exercise of the branch-cut + release-prep + release-finalize
automation. Four PRs currently open on rel-820 (openemr#12725 release-prep,
openemr#12726 release-finalize, openemr#12727 branch-cut rel-side, openemr#12728 branch-cut
master-side) each hit at least one of these. After this PR lands: close
those four + delete their branches + delete rel-820 + recreate — the
four cut-time PRs re-open fresh against the corrected mutators.

## Changes

**1. `DockerUpgradeScaffoldMutator`** — generate `fsupgrade-(N+1).sh` by
copying `fsupgrade-N.sh` in full and applying five line-level
substitutions (docker-version `N` → `N+1` in the header comment and two
echoes; prior-openemr-version marker in header comment and in the
`priorOpenemrVersion` shell variable). Previously wrote a stub that
failed ShellCheck (SC2034 on `priorOpenemrVersion`) and lacked a
trailing newline. Copy-in-full preserves the shellcheck directives,
trailing newline, and existing upgrade body from the prior file. New
test fixture: real `fsupgrade-11.sh` input + golden
`fsupgrade-12.sh.expected` showing exactly the 5-line diff.

**2. `PostReleaseTargetsMutator`** — early-return with a skipped
`MutatorResult` when no live row exists for the target rel branch in
`release-targets.yml`. Previously ran the "drop `latest` from prior
holder" step unconditionally, leaving the file with no row carrying
`latest` when release-finalize fired prematurely at cut time (openemr#12726's
symptom).

**3. `ReleasePrepCommand`** — remove `GlobalsIncMutator` from the
rel-side mutator list. Cut owns the `allow_debug_language` flip; running
it again at release-prep was defensive but hid the "did cut merge?"
question behind mutator idempotency.

**4. `DockerComposeProductionMutator`** — drop digest handling entirely.
Previously pinned `openemr/openemr:latest@sha256:X` →
`openemr/openemr:VERSION@sha256:X`, requiring `--image-digest` at
release-prep time. Chicken-and-egg: the release image is built after the
tag fires, which requires release-prep to merge. New behavior swaps only
the tag: `openemr/openemr:latest[@sha256:X]` → `openemr/openemr:VERSION`
(no digest). `MutatorContext::imageDigest` field and the
`--image-digest` CLI option are removed alongside.

**5. Docs updated** — `docs/release-automation-plan.md` (release-prep
mutator bullets reflect the new behavior) and `docs/RELEASE_PROCESS.md`
(the short "conductor rewrites" summary catches up).

## Test coverage

Per-change adequate coverage:

| Change | New/updated tests |
|---|---|
| 1. DockerUpgradeScaffold | 5 new methods + real fsupgrade-11 input +
golden fsupgrade-12 expected |
| 2. PostReleaseTargets | 2 new methods (no-live-row +
only-unreleased-placeholder cases) |
| 3. ReleasePrepCommand | 1 new method asserting GlobalsIncMutator
absent |
| 4. DockerComposeProduction | 2 test methods in MutatorTest.php updated
to reference new `pinned_tag_only_expected.yml` fixture (3 old fixtures
deleted) |
| 5. MutatorContext | `imageDigest`-specific tests removed cleanly |

Net delta: **+4 tests** on the isolated suite (new tests minus removed
imageDigest-specific).

## Verification

- `pit` clean: **3587 tests pass** in a freshly-nuked-and-recreated
docker stack
- Pre-commit hooks all green (phpstan, phpcs, rector,
composer-require-checker, codespell, conventional-commits)
- Manual audit for `imageDigest` residual references: only remaining
mention is in `DockerComposeProductionMutator.php`'s docstring
explaining the historical why (valid documentation)
- No TODO/FIXME markers left

## After merge

Clean-slate rebuild for the rel-820 cut:

```
gh pr close 12725 12726 12727 12728 --repo openemr/openemr --delete-branch
git push origin --delete rel-820
git push origin master:rel-820
```

All 4 workflows re-fire with the corrected mutators → 4 fresh PRs
against the fixed state.

Author: bradymiller

docs/RELEASE_PROCESS.md

@@ -96,7 +96,7 @@ Common envelope on every event: `{ event, repo, sha, actor, dispatched_at, data
 
 Long-lived draft PR against the `rel-*` branch, force-updated by [`.github/workflows/release-prep.yml`](../.github/workflows/release-prep.yml) on every push to a production release branch (matching `rel-[0-9]*0`, with `docs/**`-only pushes ignored). Test branches like `rel-test` go through `workflow_dispatch` instead. The mechanical edits applied by `bin/console openemr:release-prep` are documented in [`docs/release-automation-plan.md`](release-automation-plan.md) (the conductor slice plan).
 
-In short, the conductor rewrites: `version.php`, `library/globals.inc.php` (debug toggle), `docker/production/docker-compose.yml` (image pin), `src/RestControllers/OpenApi/OpenApiDefinitions.php`, `swagger/openemr-api.yaml` (regenerated from the CLI), every `docker-version` file, and (on master) a fresh `sql/X_Y_Z-to-X_Y_Z+1_upgrade.sql` skeleton.
+In short, the conductor rewrites: `version.php`, `docker/production/docker-compose.yml` (image tag pin), `src/RestControllers/OpenApi/OpenApiDefinitions.php`, and `swagger/openemr-api.yaml` (regenerated from the CLI). (The `library/globals.inc.php` debug toggle is applied by the sibling branch-cut conductor at cut time; release-prep does not re-apply it. The `docker-version` triple and `sql/*_upgrade.sql` skeleton are scaffolded at branch-cut / patch-prep time, not at ship time.)
 
 ### Docs PR — `release-docs/<version>` in `openemr/website-openemr`
 

docs/release-automation-plan.md

@@ -88,10 +88,13 @@ be auto-derived by decrementing minor below 1).
 **Rel-side PR** (`branch-cut/<rel-branch>`, base `<rel-branch>`,
 ready-for-review):
 
-- `DockerUpgradeScaffoldMutator` — new `fsupgrade-N.sh` skeleton +
-  Dockerfile manifest updates (both `COPY` and `chmod` blocks). Same
-  scaffolding the docker-upgrade-actions memo enumerates as mandatory
-  per release.
+- `DockerUpgradeScaffoldMutator` — new `fsupgrade-N.sh` (copied in full
+  from the prior `fsupgrade-N-1.sh` with only the docker-version /
+  priorOpenemrVersion header lines substituted; the upgrade body is
+  preserved byte-for-byte from the prior file for per-release refinement
+  in place) + Dockerfile manifest updates (both `COPY` and `chmod`
+  blocks). Same scaffolding the docker-upgrade-actions memo enumerates
+  as mandatory per release.
 - `DockerfileOpenemrVersionMutator` — pins the `OPENEMR_VERSION` ARG
   in the branch's Dockerfile to the new rel line.
 - `TranslationFileCopyFromPriorRelMutator` — fetches the translation
@@ -213,17 +216,24 @@ for the full picture.
 draft, force-pushed on each run):
 
 - `VersionPhpMutator` — strip `-dev` suffix from `$v_tag`.
-- `GlobalsIncMutator` — reused from branch-cut (idempotent, so re-running
-  is safe if the branch-cut PR wasn't merged before dev started).
-- `DockerComposeProductionMutator` — pin `openemr/openemr:latest@sha256:…`
-  to `openemr/openemr:<version>@sha256:…`. Image digest is supplied via
-  `--image-digest` from the workflow after the release image is published;
-  if absent, the existing digest is preserved and only the tag is swapped.
+- `DockerComposeProductionMutator` — swap the openemr image tag:
+  `openemr/openemr:latest[@sha256:…]` → `openemr/openemr:<version>` (no
+  digest). At release-prep time the release image doesn't yet exist in
+  Docker Hub (the tag→build sequence fires only after release-prep merges),
+  so there is no valid digest to pin. Any existing `@sha256:…` suffix on
+  the source line is dropped.
 - `OpenApiVersionMutator` — bump `#[OA\Info(title: 'OpenEMR API', version: 'X.Y.Z')]`.
   (The wiki + earlier drafts of this plan said `_rest_routes.inc.php` but
   the version constant actually lives in `src/RestControllers/OpenApi/OpenApiDefinitions.php`.)
 - `SwaggerRegenMutator` — regenerate `swagger/openemr-api.yaml`.
 
+`GlobalsIncMutator` is intentionally NOT in the release-prep rel-side
+list even though branch-cut runs it: re-running it here would be
+defensive but redundant, and it hides the "did branch-cut merge?"
+question behind mutator idempotency. Surface as a real diff if
+branch-cut hasn't landed yet. (Removed in round-2 fixes after the
+rel-820 first exercise; see PR #12725.)
+
 The `docker-version` files and `sql/*_upgrade.sql` skeleton the earlier
 draft of this plan enumerated for the release-prep PR moved to
 **branch-cut / patch-prep** (they're now scaffolded at the lifecycle
@@ -302,10 +312,12 @@ content on the other.
 **File overlap between the two pairs.** The branch-cut and conductor
 PRs against the same base branch touch some of the same files:
 
-- Rel-side both PRs touch `library/globals.inc.php` (branch-cut flips
-  `allow_debug_language` → `'0'`; release-prep's `GlobalsIncMutator` is
-  reused and idempotent, so a re-render sees the flag already flipped
-  and no-ops).
+- Rel-side branch-cut touches `library/globals.inc.php` (flips
+  `allow_debug_language` → `'0'`). Release-prep does NOT re-run the
+  flip — running it twice is defensive but redundant, and it hides the
+  "did branch-cut merge?" question behind mutator idempotency. If
+  branch-cut hasn't landed yet, the flip surfaces as a real diff at
+  ship time instead of a silent no-op.
 - Rel-side both touch the `docker-version` triple (branch-cut bumps by
   one for the new minor's dev cycle; release-prep leaves them alone at
   ship time).
@@ -406,8 +418,7 @@ against a shared framework at [`src/Common/Command/ReleasePrep/`](../src/Common/
 - **`MutatorInterface`** — `name(): string` + `apply(MutatorContext): MutatorResult`.
 - **`MutatorContext`** — `readonly` value object carrying `projectDir`,
   parsed `major`/`minor`/`patch`, and the optional context fields the
-  various mutators need: `imageDigest` (release-prep only, when
-  `--image-digest` is passed), `relBranch` (release-finalize, branch-cut,
+  various mutators need: `relBranch` (release-finalize, branch-cut,
   patch-prep), `prevRelBranch` (branch-cut rel-side translation copy),
   `fromVersion` (patch-prep SQL skeleton override — validated to be
   same major/minor as target with patch == target - 1). Constructor
@@ -428,8 +439,8 @@ mutators would produce churn PRs.
 |---------|---------|---------|
 | `VersionPhpMutator` | release-prep (rel) | Strip `-dev` from `$v_tag`. |
 | `VersionPhpMasterMutator` | branch-cut (master) | Advance to next-minor `-dev`. |
-| `GlobalsIncMutator` | branch-cut (rel), release-prep (rel) | `allow_debug_language = 0`. |
-| `DockerComposeProductionMutator` | release-prep (rel) | Pin `openemr/openemr` tag + digest. |
+| `GlobalsIncMutator` | branch-cut (rel) | `allow_debug_language = 0`. |
+| `DockerComposeProductionMutator` | release-prep (rel) | Pin `openemr/openemr` tag (no digest). |
 | `DockerfileOpenemrVersionMutator` | branch-cut (rel) | Pin Dockerfile `OPENEMR_VERSION` ARG. |
 | `DockerUpgradeScaffoldMutator` | branch-cut (rel + master), patch-prep (rel + master) | New `fsupgrade-N.sh` + Dockerfile manifest wiring. |
 | `TranslationFileCopyFromPriorRelMutator` | branch-cut (rel) | Fetch translation blob from prior rel branch. |

src/Common/Command/BranchCutCommand.php

@@ -139,7 +139,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $targetContext = MutatorContext::fromVersionString(
                 $projectDir,
                 $target,
-                null,
                 $relBranch,
                 $prevRelBranch,
             );
@@ -161,7 +160,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $targetContext->major,
             $targetContext->minor + 1,
             0,
-            null,
             $targetContext->relBranch,
             $targetContext->prevRelBranch,
         );

src/Common/Command/PatchPrepCommand.php

@@ -134,7 +134,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $context = MutatorContext::fromVersionString(
                 $projectDir,
                 $target,
-                null,
                 $relBranch,
                 null,
                 $prevVersion,

src/Common/Command/ReleasePrep/Mutator/DockerComposeProductionMutator.php

@@ -2,10 +2,14 @@
 
 /**
  * Pin docker/production/docker-compose.yml's openemr image from
- * `latest@sha256:...` to `<version>@sha256:...`. The published image's
- * digest is supplied via --image-digest by the conductor workflow after
- * the release image has been built and pushed; if absent the existing
- * digest is preserved and only the tag is swapped.
+ * `latest[@sha256:...]` to `<version>` (tag only, no digest).
+ *
+ * At release-prep time, the release-tagged image does not yet exist in
+ * Docker Hub — it's produced downstream only AFTER the release-prep PR
+ * merges (which triggers the tag creation which triggers the image
+ * build). So there's no valid digest to pin at this stage. The old
+ * `--image-digest` pathway assumed an out-of-band digest lookup that
+ * doesn't fit the actual sequencing; drop it and just swap the tag.
  *
  * @package   OpenEMR
  * @link      http://www.open-emr.org
@@ -30,7 +34,7 @@
 
     public function name(): string
     {
-        return 'docker/production/docker-compose.yml (pin openemr image)';
+        return 'docker/production/docker-compose.yml (pin openemr image tag)';
     }
 
     public function apply(MutatorContext $context): MutatorResult
@@ -42,29 +46,18 @@ public function apply(MutatorContext $context): MutatorResult
         }
 
         $version = $context->versionString();
-        // Accept the digest with or without the `sha256:` prefix; we always
-        // emit `@sha256:<hex>` regardless.
-        $newDigestHex = $context->imageDigest === null
-            ? null
-            : preg_replace('/^sha256:/', '', $context->imageDigest);
 
         // Pattern matches `image: openemr/openemr:<tag>` with an optional
         // `@sha256:<digest>` suffix. The tag may be `latest`, the target
-        // version, or another version (idempotence + handles re-runs after
-        // a digest update). The digest is optional because rel-* branches
-        // that were cut before the digest-pinning automation existed start
-        // with a bare tag (e.g. `openemr/openemr:8.1.0`).
-        $pattern = '/(image:\s*openemr\/openemr:)([^@\s]+)(?:(@sha256:)([0-9a-f]{64}))?/';
+        // version, or another version (idempotence + handles re-runs).
+        // The digest is optional because rel-* branches that were cut
+        // before the digest-pinning automation existed start with a bare
+        // tag (e.g. `openemr/openemr:8.1.0`). Whatever's after `:`, we
+        // replace it with the target version and strip the digest entirely.
+        $pattern = '/(image:\s*openemr\/openemr:)([^@\s]+)(?:@sha256:[0-9a-f]{64})?/';
         $updated = preg_replace_callback(
             $pattern,
-            static function (array $match) use ($version, $newDigestHex): string {
-                $existingDigest = $match[4] ?? '';
-                $digest = $newDigestHex ?? ($existingDigest !== '' ? $existingDigest : null);
-                if ($digest === null) {
-                    return $match[1] . $version;
-                }
-                return $match[1] . $version . '@sha256:' . $digest;
-            },
+            static fn (array $match): string => $match[1] . $version,
             $contents,
             1,
             $count,
@@ -95,10 +88,7 @@ static function (array $match) use ($version, $newDigestHex): string {
                 $e,
             );
         }
-        $expectedDigest = $newDigestHex ?? $this->extractDigest($contents);
-        $expectedImage = $expectedDigest === null
-            ? sprintf('openemr/openemr:%s', $version)
-            : sprintf('openemr/openemr:%s@sha256:%s', $version, $expectedDigest);
+        $expectedImage = sprintf('openemr/openemr:%s', $version);
         $actualImage = is_array($parsed)
             && is_array($parsed['services'] ?? null)
             && is_array($parsed['services']['openemr'] ?? null)
@@ -114,21 +104,9 @@ static function (array $match) use ($version, $newDigestHex): string {
         if (file_put_contents($path, $updated) === false) {
             throw new \RuntimeException('Cannot write ' . $path);
         }
-        if ($newDigestHex !== null) {
-            $messages = [];
-        } elseif ($expectedDigest === null) {
-            $messages = ['docker-compose.yml: tag pinned to ' . $version . '; no digest (source had none, no --image-digest provided)'];
-        } else {
-            $messages = ['docker-compose.yml: tag pinned to ' . $version . '; digest preserved (no --image-digest provided)'];
-        }
-        return new MutatorResult([self::RELATIVE_PATH], $messages);
-    }
-
-    private function extractDigest(string $original): ?string
-    {
-        if (preg_match('/image:\s*openemr\/openemr:[^@\s]+@sha256:([0-9a-f]{64})/', $original, $m) !== 1) {
-            return null;
-        }
-        return $m[1];
+        return new MutatorResult(
+            [self::RELATIVE_PATH],
+            ['docker-compose.yml: tag pinned to ' . $version . ' (no digest — release image is not yet built at release-prep time)'],
+        );
     }
 }