Merge pull request #3913 from tarlepp/chore(ops)/yarn-makefile-helpers

Chore(ops) - Add helpers for yarn in makefile

Author: tarlepp

Makefile

@@ -280,12 +280,25 @@ else
 	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make project-stats
 endif
 
+# Yarn upgrade and version management targets
+# See doc/YARN_UPDATE.md and doc/YARN_UPDATE_QUICK_REF.md for detailed documentation
+
 yarn: ## Compatibility target for commands like `make yarn upgrade`
 	@true
 
 upgrade: ## Alias for yarn-upgrade (supports `make yarn upgrade`)
 	@$(MAKE) yarn-upgrade VERSION=$(VERSION)
 
+yarn-status: ## Display current Yarn version information (configured, active, and latest stable)
+ifeq ($(INSIDE_DOCKER), 1)
+	@./scripts/yarn-status.sh
+else ifeq ($(strip $(IS_RUNNING)),)
+	$(WARNING_DOCKER)
+else
+	$(NOTICE_HOST)
+	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make yarn-status
+endif
+
 yarn-upgrade-check: ## Dry-run check for Yarn upgrade (no file changes)
 ifeq ($(INSIDE_DOCKER), 1)
 	@./scripts/yarn-upgrade-check.sh
@@ -306,12 +319,32 @@ else
 	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make yarn-upgrade VERSION=$(VERSION)
 endif
 
-yarn-status: ## Display current Yarn version information
+yarn-update: ## Alternative upgrade script (usage: make yarn-update VERSION=4.15.0, version is required)
 ifeq ($(INSIDE_DOCKER), 1)
+ifndef VERSION
+	@echo "\033[31mERROR: VERSION parameter is required\033[39m\nUsage: make yarn-update VERSION=4.15.0"
+	@exit 1
+else
+	@./scripts/update-yarn.sh "$(VERSION)"
+endif
+else ifeq ($(strip $(IS_RUNNING)),)
+	$(WARNING_DOCKER)
+else
+	$(NOTICE_HOST)
+	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make yarn-update VERSION=$(VERSION)
+endif
+
+yarn-check-and-upgrade: ## Convenience: check status, dry-run, then upgrade to latest stable
+ifeq ($(INSIDE_DOCKER), 1)
+	@echo "\033[32m=== Yarn Status ===\033[39m"
 	@./scripts/yarn-status.sh
+	@echo "\033[32m=== Upgrade Check (Dry-run) ===\033[39m"
+	@./scripts/yarn-upgrade-check.sh
+	@echo "\033[32m=== Upgrading to Latest Stable ===\033[39m"
+	@./scripts/yarn-upgrade.sh ""
 else ifeq ($(strip $(IS_RUNNING)),)
 	$(WARNING_DOCKER)
 else
 	$(NOTICE_HOST)
-	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make yarn-status
+	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make yarn-check-and-upgrade
 endif

doc/COMMANDS.md

@@ -19,6 +19,7 @@ commands directly from the IDE terminal.
     * [Linting and fixing](#linting-and-fixing)
     * [Translations](#translations)
     * [Maintenance utilities](#maintenance-utilities)
+      * [Yarn version management](#yarn-version-management)
   * [Yarn commands](#yarn-commands)
   * [Examples](#examples)
 
@@ -106,6 +107,25 @@ make docker-remove-containers  # Remove all Docker containers on the host
 make docker-remove-images      # Remove all Docker images on the host
 ```
 
+#### Yarn version management [ᐞ](#table-of-contents)
+
+<a id="yarn-version-management"></a>
+
+The project pins Yarn in-repo for consistent development, CI, and Docker environments.
+Manage the pinned Yarn version with these commands:
+
+```bash
+make yarn-status               # Show configured, active, and latest stable Yarn versions
+make yarn-upgrade-check        # Dry-run check for Yarn upgrade (no file changes)
+make yarn-upgrade              # Upgrade Yarn to latest stable version
+make yarn-upgrade VERSION=4.17.0  # Upgrade Yarn to a specific version
+make yarn-update VERSION=4.17.0   # Alternative upgrade approach (requires VERSION parameter)
+make yarn-check-and-upgrade    # Convenience workflow: check status, validate, then upgrade
+make yarn upgrade VERSION=4.17.0  # Compatible alias for yarn-upgrade
+```
+
+For detailed documentation, see `doc/YARN_UPDATE.md` and `doc/YARN_UPDATE_QUICK_REF.md`.
+
 ## Yarn commands [ᐞ](#table-of-contents)
 
 <a id="yarn-commands"></a>
@@ -196,6 +216,31 @@ Start development mode with immutable dependency install:
 make start-immutable
 ```
 
+Check current Yarn version and status:
+
+```bash
+make yarn-status
+```
+
+Upgrade Yarn to the latest stable version:
+
+```bash
+make yarn-upgrade
+```
+
+Upgrade Yarn to a specific version with dry-run check first:
+
+```bash
+make yarn-upgrade-check        # Validate without making changes
+make yarn-upgrade VERSION=4.17.0  # Perform the upgrade
+```
+
+Run comprehensive Yarn validation and upgrade workflow:
+
+```bash
+make yarn-check-and-upgrade
+```
+
 ---
 
 [Back to resources index](README.md) - [Back to main README.md](../README.md)

scripts/README.md

@@ -9,27 +9,96 @@ This directory contains different scripts that are used during development.
 * [What is this?](#what-is-this)
   * [Table of Contents](#table-of-contents)
   * [Resources](#resources)
+    * [Yarn management scripts](#yarn-management-scripts)
     * [Project stats script](#project-stats-script)
     * [GitHub Actions update checker](#github-actions-update-checker)
 
 ## Resources [ᐞ](#table-of-contents)
 
 <a id="resources"></a>
 
-* [Project stats script](project-stats.sh)
-  * This script is used to generate simple project stats. It will generate
-    output with some basic stats about project.
-* [GitHub Actions update checker](check-action-updates.sh)
-  * Checks pinned GitHub Actions from `.github/workflows/*.yml`, reports
-    discovery issues (unpinned refs/conflicting versions), and checks for
-    available updates in the current major version line.
+* [Yarn management scripts](#yarn-management-scripts)
+  * Manage the pinned Yarn version across the project
+* [Project stats script](#project-stats-script)
+  * Generate simple project statistics
+* [GitHub Actions update checker](#github-actions-update-checker)
+  * Check for updates to pinned GitHub Actions
+
+### Yarn management scripts [ᐞ](#table-of-contents)
+
+<a id="yarn-management-scripts"></a>
+
+The project pins Yarn in-repo for consistent development, CI, and Docker environments.
+Use these scripts via their Makefile entrypoints:
+
+**Check current state:**
+
+```bash
+make yarn-status
+```
+
+* Shows configured Yarn version, active version, latest stable, and update availability
+
+**Dry-run check (no file changes):**
+
+```bash
+make yarn-upgrade-check
+```
+
+* Performs all upgrade validations without modifying files
+
+**Upgrade to latest stable:**
+
+```bash
+make yarn-upgrade
+```
+
+* Automatically detects and upgrades to the latest stable Yarn version
+
+**Upgrade to explicit version:**
+
+```bash
+make yarn-upgrade VERSION=4.17.0
+```
+
+* Compatible alias: `make yarn upgrade VERSION=4.17.0`
+* Updates `package.json`, `.yarnrc.yml`, and `.yarn/releases/`
+
+**Alternative upgrade approach:**
+
+```bash
+make yarn-update VERSION=4.17.0
+```
+
+* Uses `scripts/update-yarn.sh` with detailed step-by-step output
+* Requires explicit VERSION parameter
+
+**Convenience workflow (check, validate, then upgrade):**
+
+```bash
+make yarn-check-and-upgrade
+```
+
+* Runs: `yarn-status` → `yarn-upgrade-check` → `yarn-upgrade` sequentially
+
+Scripts referenced:
+
+* `scripts/yarn-lib.sh` - Shared helper functions
+* `scripts/yarn-status.sh` - Display current versions
+* `scripts/yarn-upgrade.sh` - Primary upgrade script
+* `scripts/yarn-upgrade-check.sh` - Dry-run validation
+* `scripts/update-yarn.sh` - Alternative upgrade with detailed output
+
+See `doc/YARN_UPDATE.md` and `doc/YARN_UPDATE_QUICK_REF.md` for detailed documentation.
 
 ### Project stats script [ᐞ](#table-of-contents)
 
 <a id="project-stats-script"></a>
 
 File: `scripts/project-stats.sh`
 
+Generate simple project statistics:
+
 ```bash
 make project-stats
 ```