build: Remove additional UI5 CLI packages from npm workspace

The UI5 CLI packages have been added to the npm workspace (documentation package)
in order to generate JSDoc and build the JSON schema files for the gh-pages
deployment which should be based on the published packages rather than the local
source code.

This has caused issues during the release process where versions were adjusted
incorrectly by release please during the version bump.

The packages are now downloaded as tarballs from the npm registry during the
build process using a new script (downloadPackages.sh).

This prevents any interference with the npm workspace.
It also reduces the local installation size during development.

In addition, obsolete dependencies have been removed from the root package.json.

Author: matz3

.github/workflows/deploy-vitepress-docs.yaml

@@ -56,12 +56,15 @@ jobs:
                 # The alias output
                 npm run build:vitepress -- --base="/${{ github.event.repository.name }}/${DOC_ALIAS}/" --outDir="dist-${DOC_ALIAS}"
                 npm run build:assets -- ./dist-${DOC_ALIAS}
+            - name: Download UI5 CLI packages
+              working-directory: internal/documentation
+              run: npm run download-packages
             - name: Build jsdoc
               working-directory: internal/documentation
-              run: npm run jsdoc-generate
+              run: npm run jsdoc-generate-gh-pages
             - name: Build Schema
               working-directory: internal/documentation
-              run: npm run schema-generate
+              run: npm run schema-generate-gh-pages
             - name: Checkout gh-pages
               uses: actions/checkout@v5
               with:

.github/workflows/github-ci.yml

@@ -39,14 +39,26 @@ jobs:
     - name: Run unit tests
       run: npm run coverage
 
-    - name: Generate JSDoc documentation
+    - name: Generate JSDoc documentation (workspace)
       working-directory: internal/documentation
       run: npm run jsdoc-generate
 
-    - name: Generate merged JSON schema
+    - name: Generate merged JSON schema (workspace)
       working-directory: internal/documentation
       run: npm run schema-generate
 
+    - name: Download UI5 CLI packages
+      working-directory: internal/documentation
+      run: npm run download-packages
+
+    - name: Generate JSDoc documentation (gh-pages)
+      working-directory: internal/documentation
+      run: npm run jsdoc-generate-gh-pages
+
+    - name: Generate merged JSON schema (gh-pages)
+      working-directory: internal/documentation
+      run: npm run schema-generate-gh-pages
+
     - name: Generate CLI documentation
       working-directory: internal/documentation
       run: npm run generate-cli-doc

.github/workflows/release-please.yml

@@ -45,17 +45,6 @@ jobs:
           # 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
@@ -84,13 +73,13 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: 24.x
-          
+
       - name: Install dependencies
         run: npm ci
 
       - name: Publish ${{ matrix.package }} package
         working-directory: packages/${{ matrix.package }}
-        run: | 
+        run: |
           echo "🚀 Publishing @ui5/${{ matrix.package }}"
           npm publish --access public --tag next
 

.gitignore

@@ -68,3 +68,4 @@ internal/documentation/.vitepress/dist
 internal/documentation/.vitepress/cache
 internal/documentation/dist
 internal/documentation/schema/*
+internal/documentation/tmp

internal/documentation/jsdoc/jsdoc.json

@@ -3,15 +3,14 @@
 		"allowUnknownTags": false
 	},
 	"source": {
-		"include": ["jsdoc/index.md", "../../node_modules/@ui5"],
+		"include": ["jsdoc/index.md"],
 		"exclude": [
-			"../../node_modules/@ui5/builder-npm/lib/lbt/utils/JSTokenizer.js",
-			"../../node_modules/@ui5/builder-npm/lib/processors/jsdoc/lib/ui5/plugin.js",
-			"../../node_modules/@ui5/builder-npm/lib/processors/jsdoc/lib/ui5/template/publish.js",
-			"../../node_modules/@ui5/builder-npm/lib/processors/jsdoc/lib/ui5/template/utils/versionUtil.js"
+			"tmp/packages/@ui5/builder/lib/lbt/utils/JSTokenizer.js",
+			"tmp/packages/@ui5/builder/lib/processors/jsdoc/lib/ui5/plugin.js",
+			"tmp/packages/@ui5/builder/lib/processors/jsdoc/lib/ui5/template/publish.js",
+			"tmp/packages/@ui5/builder/lib/processors/jsdoc/lib/ui5/template/utils/versionUtil.js"
 		],
-		"includePattern": "@ui5/[^/]*-npm/(lib/.+|index)\\.js$",
-		"excludePattern": "@ui5/.*/node_modules/@ui5"
+		"includePattern": "tmp/packages/@ui5/[^/]*/(lib/.+|index)\\.js$"
 	},
 	"plugins": [
 		"jsdoc/jsdoc-plugin.cjs"

internal/documentation/package.json

@@ -24,17 +24,18 @@
 	"scripts": {
 		"start": "vitepress dev --open",
 		"lint": "eslint .",
-		"depcheck": "depcheck --ignores @ui5/documentation,vitepress,docdash,jsdoc,open-cli,handlebars,@types/node,@ui5/webcomponents,autoprefixer,cssnano,@ui5/cli-npm,@ui5/builder-npm,@ui5/fs-npm,@ui5/logger-npm,@ui5/project-npm,@ui5/server-npm,@theme/components",
+		"depcheck": "depcheck --ignores @ui5/documentation,vitepress,docdash,jsdoc,open-cli,handlebars,@types/node,@ui5/webcomponents,autoprefixer,cssnano,@theme/components",
 		"dev": "vitepress dev",
 		"build:vitepress": "vitepress build",
 		"build:assets": "sh -c 'DEST_DIR=${1:-./dist}; cp -r ./docs/images \"$DEST_DIR/images\"' --",
 		"preview": "vitepress preview --port 8080",
 		"jsdoc": "npm run jsdoc-generate && open-cli dist/api/index.html",
-		"jsdoc-generate": "jsdoc -c jsdoc/jsdoc.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
-		"jsdoc-generate-workspace": "jsdoc -c jsdoc/jsdoc-workspace.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
+		"jsdoc-generate": "jsdoc -c jsdoc/jsdoc-workspace.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
+		"jsdoc-generate-gh-pages": "jsdoc -c jsdoc/jsdoc.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
 		"generate-cli-doc": "node ./scripts/generateCliDoc.js",
-		"schema-generate": "node ./scripts/buildSchema.js @ui5/project-npm",
-		"schema-generate-workspace": "node ./scripts/buildSchema.js @ui5/project"
+		"schema-generate": "node ./scripts/buildSchema.js",
+		"schema-generate-gh-pages": "node ./scripts/buildSchema.js gh-pages",
+		"download-packages": "./scripts/downloadPackages.sh"
 	},
 	"dependencies": {
 		"@types/node": "^22.5.1",
@@ -49,12 +50,6 @@
 	},
 	"devDependencies": {
 		"@apidevtools/json-schema-ref-parser": "^14.2.1",
-		"@ui5/builder-npm": "npm:@ui5/builder@^4.0.11",
-		"@ui5/cli-npm": "npm:@ui5/cli@^4.0.26",
-		"@ui5/fs-npm": "npm:@ui5/fs@^4.0.2",
-		"@ui5/logger-npm": "npm:@ui5/logger@^4.0.2",
-		"@ui5/project-npm": "npm:@ui5/project@^4.0.6",
-		"@ui5/server-npm": "npm:@ui5/server@^4.0.7",
 		"docdash": "^2.0.2",
 		"handlebars": "^4.7.8",
 		"jsdoc": "^4.0.4",

internal/documentation/scripts/buildSchema.js

@@ -4,21 +4,30 @@ import {writeFile, mkdir} from "node:fs/promises";
 import {$RefParser} from "@apidevtools/json-schema-ref-parser";
 import traverse from "traverse";
 
-// Read the given CLI parameter to set which UI5/project version to use.
-// Default to "@ui5/project-npm" to use the latest published version (for Github Pages).
-// For testing, the local version can be used by providing "@ui5/project".
-// Example: node buildSchema.js @ui5/project-npm
-// Example: node buildSchema.js @ui5/project
-const UI5_PROJECT_VERSION = process.argv[2] || "@ui5/project-npm";
+// Read the given CLI parameter to determine in which mode to run the script:
+// - workspace (default): Use @ui5/project from local workspace (packages/project)
+// - gh-pages: Use published version of @ui5/project from npm (downloaded via "downloadPackages.sh" beforehand)
+const MODE = process.argv[2] || "workspace";
 
 try {
+	// Determine base URL for resolving schema files based on the mode
+	let BASE_URL;
+	if (MODE === "workspace") {
+		BASE_URL = import.meta.resolve(`@ui5/project/package.json`);
+	} else if (MODE === "gh-pages") {
+		BASE_URL = new URL("../tmp/packages/@ui5/project/package.json", import.meta.url);
+	} else {
+		throw new Error(`Unknown mode: '${MODE}'. Supported modes are 'workspace' and 'gh-pages'.`);
+	}
+
+	console.log(`Building JSON Schema files in mode '${MODE}' using package at: ${BASE_URL}`);
+
 	// Use ui5.yaml.json and ui5-workspace.yaml.json
 	const schemaNames = ["ui5", "ui5-workspace"];
 
 	schemaNames.forEach(async (schemaName) => {
 		const SOURCE_SCHEMA_PATH = fileURLToPath(
-			new URL(`./lib/validation/schema/${schemaName}.json`,
-				import.meta.resolve(`${UI5_PROJECT_VERSION}/package.json`))
+			new URL(`./lib/validation/schema/${schemaName}.json`, BASE_URL)
 		);
 		const TARGET_SCHEMA_PATH = fileURLToPath(
 			new URL(`../schema/${schemaName}.yaml.json`, import.meta.url)

internal/documentation/scripts/downloadPackages.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+set -euo pipefail
+
+# Constants
+readonly UI5_CLI_PACKAGES_VERSION="latest"
+readonly UI5_CLI_PACKAGES=($(find ../../packages/*/package.json -exec jq -r '.name' {} \;))
+
+# Directories
+readonly SCRIPT_DIR="$(dirname -- "$0")"
+readonly DOC_ROOT="${SCRIPT_DIR}/.."
+readonly TMP_PACKAGES_DIR="./tmp/packages"
+
+# Functions
+extract_package_file_name() {
+	local package="$1"
+
+	# Remove "@" from scoped package names
+	local package_file_name="${package#@}"
+
+	# Replace "/" with "-" for file name
+	package_file_name="${package_file_name//\//-}"
+
+	echo "$package_file_name"
+}
+
+download_packages() {
+	echo "Downloading UI5 CLI packages for JSDoc / JSON Schema generation..."
+
+	mkdir -p "$TMP_PACKAGES_DIR"
+
+	for package in "${UI5_CLI_PACKAGES[@]}"; do
+		echo "Downloading and extracting $package..."
+		npm pack "$package@$UI5_CLI_PACKAGES_VERSION" --workspaces false --quiet --pack-destination "$TMP_PACKAGES_DIR"
+		local package_file_name="$(extract_package_file_name "$package")"
+		rm -rf "$TMP_PACKAGES_DIR/${package}"
+		mkdir -p "$TMP_PACKAGES_DIR/${package}"
+		tar -xzf "$TMP_PACKAGES_DIR/${package_file_name}"-*.tgz --strip-components=1 -C "$TMP_PACKAGES_DIR/${package}"
+		rm "$TMP_PACKAGES_DIR/${package_file_name}"-*.tgz
+	done
+}
+
+main() {
+	cd "$DOC_ROOT"
+	echo "Changed directory to $(pwd)"
+
+	download_packages
+}
+
+main "$@"