ci: Refactor automated release and publishing workflows with Release Please (#1215)

JIRA: CPOUI5FOUNDATION-1166

## 🔧 Technical Challenges & Solutions

### 1. Circular Peer Dependencies

**Problem:** `@ui5/project` has `peerDependency` on `@ui5/builder`,
while `@ui5/builder` has `devDependency` on `@ui5/project`. The
`node-workspace` plugin detected this cycle:

```
Error: found cycle in dependency graph: @ui5/builder -> @ui5/project -> @ui5/builder
```

**Solution:**
- Configured `node-workspace` plugin with `updatePeerDependencies: true`
- Added automated workflow step that manually updates `@ui5/builder`
peer dependency in `packages/project/package.json`
- Uses `jq` for surgical JSON manipulation to update version range from
`^4.x` to `^5.x`

```yaml
BUILDER_VERSION=$(jq -r '.version' packages/builder/package.json)
jq --tab --arg new_version "^$BUILDER_VERSION" \
  '.peerDependencies."@ui5/builder" = $new_version' \
  packages/project/package.json > tmp.$$.json
```

### 2. Package-Lock Corruption from npm Aliases

**Problem:** The `node-workspace` plugin corrupted `package-lock.json`
by updating npm alias entries in `internal/documentation/package.json`.
This created inconsistent lockfile entries mixing workspace versions
with registry URLs:

```json
"node_modules/@ui5/fs-npm": {
  "name": "@ui5/fs",
  "version": "5.0.0-alpha.0",  // ❌ New workspace version
  "resolved": "https://registry.npmjs.org/@ui5/fs/-/fs-4.0.3.tgz",  // ❌ Old registry URL
  "integrity": "sha512-..."
}
```

**Solution:**
Implemented automated lockfile restoration that:
1. Runs `npm install` to regenerate workspace lockfile entries
2. Selectively restores npm alias entries from `origin/main` using `jq`
3. Preserves workspace updates while keeping npm aliases at stable
registry versions

```bash
# Restore npm alias entries from main branch
git show origin/main:package-lock.json | \
  jq -r '.packages | to_entries[] | 
    select(.key | test("node_modules/@ui5/(builder|cli|fs|logger|project|server)-npm$")) | 
    .key' | while read key; do
  original_entry=$(git show origin/main:package-lock.json | jq ".packages[\"$key\"]")
  jq --tab --arg key "$key" --argjson entry "$original_entry" \
    '.packages[$key] = $entry' package-lock.json > tmp.$$.json
  mv tmp.$$.json package-lock.json
done
```

### 3. PR Title Version Extraction

**Problem:** Release Please's `${version}` template doesn't work with
grouped monorepo releases using the `linked-versions` plugin (no root
package context).

**Solution:**
- Used `${branch}` in PR title pattern: `"release: UI5 CLI packages
${branch}"`
- Final title: `"release: UI5 CLI packages main"`

Author: d3xter666

.github/workflows/release-please.yml

@@ -13,6 +13,8 @@ permissions:
 jobs:
   release-please:
     runs-on: ubuntu-24.04
+    outputs:
+      releases_created: ${{ steps.release.outputs.releases_created }}
     steps:
       - uses: actions/checkout@v5
 
@@ -27,6 +29,44 @@ jobs:
         with:
           token: "${{ secrets.GITHUB_TOKEN }}"
 
+      - name: "Fix peerDependency and lockfile in Release PR"
+        if: ${{ steps.release.outputs.pr }}
+        run: |
+          set -ex
+          gh pr checkout ${{ fromJson(steps.release.outputs.pr).number }}
+
+          # Update peer dependency: Release Please doesn't handle circular peerDependencies
+          # @ui5/project has peerDependency on @ui5/builder, and @ui5/builder has devDependency on @ui5/project
+          # The node-workspace plugin can't resolve this cycle, so we update it manually
+          # Extract builder version and update project peer dependency
+          BUILDER_VERSION=$(jq -r '.version' packages/builder/package.json)
+          jq --tab --arg new_version "^$BUILDER_VERSION" '.peerDependencies."@ui5/builder" = $new_version' packages/project/package.json > tmp.$$.json && mv tmp.$$.json packages/project/package.json
+
+          # Regenerate package-lock.json to sync with updated workspace packages
+          npm install
+
+          # Fix lockfile corruption: node-workspace plugin updates npm alias entries in package-lock.json
+          # but the internal/* packages have npm aliases (@ui5/builder-npm, @ui5/cli-npm, etc.) that point
+          # to old versions (^4.0.x) which are still correct and should not be updated to new versions (^5.0.x)
+          # that don't exist on npm yet. We restore these specific entries from the main branch.
+          # Restore original entries for @ui5/*-npm packages to avoid unintended updates
+          # Note: npm aliases can be in node_modules or internal/documentation/node_modules
+          git show origin/main:package-lock.json | jq -r '.packages | to_entries[] | select(.key | test("(node_modules|internal/documentation/node_modules)/@ui5/(builder|cli|fs|logger|project|server)-npm$")) | .key' | while read key; do
+            original_entry=$(git show origin/main:package-lock.json | jq ".packages[\"$key\"]")
+            jq --tab --arg key "$key" --argjson entry "$original_entry" '.packages[$key] = $entry' package-lock.json > tmp.$$.json && mv tmp.$$.json package-lock.json
+          done
+
+          # Commit the change back to the PR branch
+          # Amend the Release Please commit to include our fixes
+          # This keeps the PR clean with a single commit
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add packages/project/package.json package-lock.json
+          git commit --amend --no-edit
+          git push --force-with-lease
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
   publish-packages:
     runs-on: ubuntu-24.04
     needs: release-please
@@ -79,4 +119,4 @@ jobs:
         working-directory: packages/cli
         run: |
           echo "🚀 Publishing @ui5/cli"
-          npm publish --access public --tag next
+          npm publish --access public --tag next

release-please-config.json

@@ -1,8 +1,11 @@
 {
 	"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
-	"group-pull-request-title-pattern": "release: UI5 CLI packages",
-	"prerelease-type": "alpha",
+	"group-pull-request-title-pattern": "release: UI5 CLI packages ${branch}",
+	"release-type": "node",
+	"always-update": true,
+	"pull-request-header": ":tractor: New release prepared",
 	"prerelease": true,
+	"prerelease-type": "alpha",
 	"release-as": "5.0.0-alpha.0",
 	"packages": {
 		"packages/logger": {
@@ -27,13 +30,10 @@
 			]
 		}
 	},
-	"release-type": "node",
-	"always-update": true,
-	"pull-request-header": ":tractor: New release prepared",
-	"pull-request-title-pattern": "release: UI5 CLI packages",
 	"plugins": [
 		{
-			"type": "node-workspace"
+			"type": "node-workspace",
+			"merge": false
 		},
 		{
 			"type": "linked-versions",