From 57d39f7052d5e5f76dd4836beee08fc2b8bc2d3b Mon Sep 17 00:00:00 2001
From: i343759 <teodora.nikolova@sap.com>
Date: Thu, 24 Sep 2026 11:27:58 +0300
Subject: [PATCH] Add Yarn Berry (2.x/3.x/4.x) support

Detects Yarn Berry via the presence of .yarnrc.yml (the marker file
Yarn Berry itself uses to identify a project - Yarn Classic projects
never have this file). When detected:

- InstallYarnBerry() installs the new yarn-berry dependency (a single
  bundled CLI script, not a tarball - see
  https://repo.yarnpkg.com) instead of classic yarn, and shims a
  wrapper script on PATH so 'yarn' still resolves to a working
  executable via 'node <script> "$@"'.
- Yarn.Build() branches to a Berry-specific install path
  ('yarn install --immutable'), since Berry's CLI does not support
  Classic-only flags/subcommands used today (--pure-lockfile,
  --ignore-engines, --cache-folder, 'yarn config set', offline
  mirror). Berry manages its own cache/linker behavior via the
  project's own .yarnrc.yml, which is left untouched.

Classic Yarn (yarn.lock without .yarnrc.yml) behavior is completely
unchanged.

Depends on the yarn-berry dependency added to the buildpack manifest
via the dependency-builds pipeline (cloudfoundry/buildpacks-ci#673).
---
 src/nodejs/supply/mocks_test.go  | 10 ++--
 src/nodejs/supply/supply.go      | 79 ++++++++++++++++++++++++++--
 src/nodejs/supply/supply_test.go | 90 +++++++++++++++++++++++++++++++-
 src/nodejs/yarn/yarn.go          | 28 +++++++++-
 src/nodejs/yarn/yarn_test.go     | 12 ++---
 5 files changed, 201 insertions(+), 18 deletions(-)

diff --git a/src/nodejs/supply/mocks_test.go b/src/nodejs/supply/mocks_test.go
index dd78457ec..3aa86e885 100644
--- a/src/nodejs/supply/mocks_test.go
+++ b/src/nodejs/supply/mocks_test.go
@@ -1,5 +1,5 @@
 // Code generated by MockGen. DO NOT EDIT.
-// Source: supply.go
+// Source: src/nodejs/supply/supply.go
 
 // Package supply_test is a generated GoMock package.
 package supply_test
@@ -232,17 +232,17 @@ func (m *MockYarn) EXPECT() *MockYarnMockRecorder {
 }
 
 // Build mocks base method.
-func (m *MockYarn) Build(arg0, arg1 string) error {
+func (m *MockYarn) Build(buildDir, cacheDir string, isBerry bool) error {
 	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "Build", arg0, arg1)
+	ret := m.ctrl.Call(m, "Build", buildDir, cacheDir, isBerry)
 	ret0, _ := ret[0].(error)
 	return ret0
 }
 
 // Build indicates an expected call of Build.
-func (mr *MockYarnMockRecorder) Build(arg0, arg1 interface{}) *gomock.Call {
+func (mr *MockYarnMockRecorder) Build(buildDir, cacheDir, isBerry interface{}) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Build", reflect.TypeOf((*MockYarn)(nil).Build), arg0, arg1)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Build", reflect.TypeOf((*MockYarn)(nil).Build), buildDir, cacheDir, isBerry)
 }
 
 // MockStager is a mock of Stager interface.
diff --git a/src/nodejs/supply/supply.go b/src/nodejs/supply/supply.go
index 5d687091e..46385f550 100644
--- a/src/nodejs/supply/supply.go
+++ b/src/nodejs/supply/supply.go
@@ -45,7 +45,7 @@ type NPM interface {
 }
 
 type Yarn interface {
-	Build(string, string) error
+	Build(buildDir, cacheDir string, isBerry bool) error
 }
 
 type Stager interface {
@@ -77,6 +77,7 @@ type Supplier struct {
 	PostBuild              string
 	UseYarn                bool
 	UsesYarnWorkspaces     bool
+	UsesYarnBerry          bool
 	IsVendored             bool
 	Yarn                   Yarn
 	NPM                    NPM
@@ -124,9 +125,16 @@ func Run(s *Supplier) error {
 			return err
 		}
 
-		if err := s.InstallYarn(); err != nil {
-			s.Log.Error("Unable to install yarn: %s", err.Error())
-			return err
+		if s.UsesYarnBerry {
+			if err := s.InstallYarnBerry(); err != nil {
+				s.Log.Error("Unable to install yarn (berry): %s", err.Error())
+				return err
+			}
+		} else {
+			if err := s.InstallYarn(); err != nil {
+				s.Log.Error("Unable to install yarn: %s", err.Error())
+				return err
+			}
 		}
 
 		if err := s.CreateDefaultEnv(); err != nil {
@@ -317,7 +325,7 @@ func (s *Supplier) BuildDependencies() error {
 
 	switch {
 	case s.UseYarn:
-		if err := s.Yarn.Build(s.Stager.BuildDir(), s.Stager.CacheDir()); err != nil {
+		if err := s.Yarn.Build(s.Stager.BuildDir(), s.Stager.CacheDir(), s.UsesYarnBerry); err != nil {
 			return err
 		}
 
@@ -400,6 +408,16 @@ func (s *Supplier) ReadPackageJSON() error {
 		return err
 	}
 
+	if s.UseYarn {
+		// .yarnrc.yml is the marker file Yarn Berry (2.x/3.x/4.x) itself uses to
+		// identify a project as using the "modern" (non-Classic) CLI/protocol -
+		// Yarn Classic (1.x) projects never have this file. See
+		// https://yarnpkg.com/configuration/yarnrc.
+		if s.UsesYarnBerry, err = libbuildpack.FileExists(filepath.Join(s.Stager.BuildDir(), ".yarnrc.yml")); err != nil {
+			return err
+		}
+	}
+
 	if s.IsVendored, err = libbuildpack.FileExists(filepath.Join(s.Stager.BuildDir(), "node_modules")); err != nil {
 		return err
 	}
@@ -799,6 +817,57 @@ func (s *Supplier) InstallYarn() error {
 	return nil
 }
 
+// InstallYarnBerry installs the "yarn-berry" dependency (Yarn 2.x/3.x/4.x) for
+// projects whose .yarnrc.yml marks them as using the modern Yarn CLI.
+//
+// Unlike Yarn Classic, Yarn Berry is not distributed as a self-contained
+// installable tarball with a bin/ directory - it ships as a single bundled
+// CLI script (see https://repo.yarnpkg.com). InstallOnlyVersion therefore
+// just copies that file as-is into the install dir (libbuildpack falls back
+// to a plain copy for any dependency URI it doesn't recognize as an
+// archive), so a small wrapper script is created here to expose it on PATH
+// as a normal "yarn" executable via `node <script> "$@"`.
+func (s *Supplier) InstallYarnBerry() error {
+	yarnBerryInstallDir := filepath.Join(s.Stager.DepDir(), "yarn-berry")
+
+	if err := s.Installer.InstallOnlyVersion("yarn-berry", yarnBerryInstallDir); err != nil {
+		return err
+	}
+
+	matches, err := filepath.Glob(filepath.Join(yarnBerryInstallDir, "*.js"))
+	if err != nil {
+		return err
+	}
+	if len(matches) == 0 {
+		return fmt.Errorf("could not locate yarn-berry CLI script in %s", yarnBerryInstallDir)
+	}
+	yarnBerryScript := matches[0]
+
+	binDir := filepath.Join(yarnBerryInstallDir, "bin")
+	if err := os.MkdirAll(binDir, 0755); err != nil {
+		return err
+	}
+
+	shim := fmt.Sprintf("#!/usr/bin/env bash\nexec node \"%s\" \"$@\"\n", yarnBerryScript)
+	if err := os.WriteFile(filepath.Join(binDir, "yarn"), []byte(shim), 0755); err != nil {
+		return err
+	}
+
+	if err := s.Stager.LinkDirectoryInDepDir(binDir, "bin"); err != nil {
+		return err
+	}
+
+	buffer := new(bytes.Buffer)
+	if err := s.Command.Execute(s.Stager.BuildDir(), buffer, buffer, "yarn", "--version"); err != nil {
+		return err
+	}
+
+	yarnVersion := strings.TrimSpace(buffer.String())
+	s.Log.Info("Installed yarn (berry) %s", yarnVersion)
+
+	return nil
+}
+
 func (s *Supplier) CreateDefaultEnv() error {
 	var environmentDefaults = map[string]string{
 		"NODE_ENV":              "production",
diff --git a/src/nodejs/supply/supply_test.go b/src/nodejs/supply/supply_test.go
index 0d02e3187..02b59aa81 100644
--- a/src/nodejs/supply/supply_test.go
+++ b/src/nodejs/supply/supply_test.go
@@ -658,6 +658,46 @@ var _ = Describe("Supply", func() {
 		})
 	})
 
+	Describe("InstallYarnBerry", func() {
+		var yarnBerryInstallDir string
+
+		BeforeEach(func() {
+			yarnBerryInstallDir = filepath.Join(depsDir, depsIdx, "yarn-berry")
+
+			mockInstaller.EXPECT().InstallOnlyVersion("yarn-berry", yarnBerryInstallDir).Do(func(_ string, installDir string) {
+				Expect(os.MkdirAll(installDir, 0755)).To(Succeed())
+				Expect(os.WriteFile(filepath.Join(installDir, "yarn-berry-4.18.0.js"), []byte("#!/usr/bin/env node\n"), 0644)).To(Succeed())
+			}).Return(nil)
+
+			mockCommand.EXPECT().Execute(buildDir, gomock.Any(), gomock.Any(), "yarn", "--version").Do(func(_ string, buffer io.Writer, _ io.Writer, _ string, _ ...string) {
+				buffer.Write([]byte("4.18.0\n"))
+			}).Return(nil)
+		})
+
+		It("installs the yarn-berry CLI script", func() {
+			err = supplier.InstallYarnBerry()
+			Expect(err).To(BeNil())
+			Expect(buffer.String()).To(ContainSubstring("Installed yarn (berry) 4.18.0"))
+		})
+
+		It("creates an executable wrapper script in <depDir>/bin that execs the CLI script with node", func() {
+			err = supplier.InstallYarnBerry()
+			Expect(err).To(BeNil())
+
+			link, err := os.Readlink(filepath.Join(depsDir, depsIdx, "bin", "yarn"))
+			Expect(err).To(BeNil())
+			Expect(link).To(Equal("../yarn-berry/bin/yarn"))
+
+			shimContents, err := os.ReadFile(filepath.Join(yarnBerryInstallDir, "bin", "yarn"))
+			Expect(err).To(BeNil())
+			Expect(string(shimContents)).To(ContainSubstring(`exec node "` + filepath.Join(yarnBerryInstallDir, "yarn-berry-4.18.0.js") + `" "$@"`))
+
+			info, err := os.Stat(filepath.Join(yarnBerryInstallDir, "bin", "yarn"))
+			Expect(err).To(BeNil())
+			Expect(info.Mode().Perm()&0111).ToNot(BeZero(), "shim script should be executable")
+		})
+	})
+
 	Describe("InstallNPM", func() {
 		BeforeEach(func() {
 			mockCommand.EXPECT().Execute(buildDir, gomock.Any(), gomock.Any(), "npm", "--version", "--loglevel", "notice").Do(func(_ string, buffer io.Writer, _ io.Writer, _ string, _ ...string) {
@@ -796,6 +836,39 @@ var _ = Describe("Supply", func() {
 			})
 		})
 
+		Context("yarn.lock and .yarnrc.yml both exist", func() {
+			BeforeEach(func() {
+				Expect(os.WriteFile(filepath.Join(buildDir, "yarn.lock"), []byte("{}"), 0644)).To(Succeed())
+				Expect(os.WriteFile(filepath.Join(buildDir, ".yarnrc.yml"), []byte("yarnPath: .yarn/releases/yarn-4.18.0.cjs\n"), 0644)).To(Succeed())
+			})
+			It("sets UsesYarnBerry to true", func() {
+				Expect(supplier.ReadPackageJSON()).To(Succeed())
+				Expect(supplier.UseYarn).To(BeTrue())
+				Expect(supplier.UsesYarnBerry).To(BeTrue())
+			})
+		})
+
+		Context("yarn.lock exists but .yarnrc.yml does not", func() {
+			BeforeEach(func() {
+				Expect(os.WriteFile(filepath.Join(buildDir, "yarn.lock"), []byte("{}"), 0644)).To(Succeed())
+			})
+			It("sets UsesYarnBerry to false (Yarn Classic)", func() {
+				Expect(supplier.ReadPackageJSON()).To(Succeed())
+				Expect(supplier.UsesYarnBerry).To(BeFalse())
+			})
+		})
+
+		Context(".yarnrc.yml exists but yarn.lock does not", func() {
+			BeforeEach(func() {
+				Expect(os.WriteFile(filepath.Join(buildDir, ".yarnrc.yml"), []byte("yarnPath: .yarn/releases/yarn-4.18.0.cjs\n"), 0644)).To(Succeed())
+			})
+			It("sets UsesYarnBerry to false (not a yarn project)", func() {
+				Expect(supplier.ReadPackageJSON()).To(Succeed())
+				Expect(supplier.UseYarn).To(BeFalse())
+				Expect(supplier.UsesYarnBerry).To(BeFalse())
+			})
+		})
+
 		Context("node_modules exists", func() {
 			BeforeEach(func() {
 				Expect(os.MkdirAll(filepath.Join(buildDir, "node_modules"), 0755)).To(Succeed())
@@ -1088,7 +1161,7 @@ var _ = Describe("Supply", func() {
 		Context("using yarn", func() {
 			BeforeEach(func() {
 				supplier.UseYarn = true
-				mockYarn.EXPECT().Build(buildDir, cacheDir).DoAndReturn(func(string, string) error {
+				mockYarn.EXPECT().Build(buildDir, cacheDir, false).DoAndReturn(func(string, string, bool) error {
 					Expect(os.MkdirAll(filepath.Join(buildDir, "node_modules"), 0755)).To(Succeed())
 					return nil
 				})
@@ -1113,6 +1186,21 @@ var _ = Describe("Supply", func() {
 			})
 		})
 
+		Context("using yarn berry", func() {
+			BeforeEach(func() {
+				supplier.UseYarn = true
+				supplier.UsesYarnBerry = true
+				mockYarn.EXPECT().Build(buildDir, cacheDir, true).DoAndReturn(func(string, string, bool) error {
+					Expect(os.MkdirAll(filepath.Join(buildDir, "node_modules"), 0755)).To(Succeed())
+					return nil
+				})
+			})
+
+			It("passes isBerry=true through to Yarn.Build", func() {
+				Expect(supplier.BuildDependencies()).To(Succeed())
+			})
+		})
+
 		Describe("using npm", func() {
 			BeforeEach(func() {
 				supplier.UseYarn = false
diff --git a/src/nodejs/yarn/yarn.go b/src/nodejs/yarn/yarn.go
index 3646294ee..713b82a6a 100644
--- a/src/nodejs/yarn/yarn.go
+++ b/src/nodejs/yarn/yarn.go
@@ -19,7 +19,33 @@ type Yarn struct {
 	Log     *libbuildpack.Logger
 }
 
-func (y *Yarn) Build(buildDir, cacheDir string) error {
+func (y *Yarn) Build(buildDir, cacheDir string, isBerry bool) error {
+	if isBerry {
+		return y.buildBerry(buildDir)
+	}
+	return y.buildClassic(buildDir, cacheDir)
+}
+
+// buildBerry installs dependencies using the Yarn Berry (2.x/3.x/4.x) CLI.
+//
+// Berry's CLI is not backwards compatible with Classic's flags: there is no
+// "yarn config set", "--pure-lockfile", "--ignore-engines", or
+// "--cache-folder" equivalent. Berry manages its own cache/linker behavior
+// via the project's own .yarnrc.yml, which is left untouched here. The
+// closest equivalent to Classic's "--pure-lockfile" (fail rather than
+// silently update the lockfile) is Berry's "--immutable" flag.
+func (y *Yarn) buildBerry(buildDir string) error {
+	y.Log.Info("Installing node modules (yarn.lock) [yarn berry]")
+
+	cmd := exec.Command("yarn", "install", "--immutable")
+	cmd.Dir = buildDir
+	cmd.Stdout = y.Log.Output()
+	cmd.Stderr = y.Log.Output()
+	cmd.Env = append(os.Environ(), "npm_config_nodedir="+os.Getenv("NODE_HOME"))
+	return y.Command.Run(cmd)
+}
+
+func (y *Yarn) buildClassic(buildDir, cacheDir string) error {
 	y.Log.Info("Installing node modules (yarn.lock)")
 
 	offline, err := libbuildpack.FileExists(filepath.Join(buildDir, "npm-packages-offline-cache"))
diff --git a/src/nodejs/yarn/yarn_test.go b/src/nodejs/yarn/yarn_test.go
index 5f23c3fb4..d98b78beb 100644
--- a/src/nodejs/yarn/yarn_test.go
+++ b/src/nodejs/yarn/yarn_test.go
@@ -89,14 +89,14 @@ var _ = Describe("Yarn", func() {
 			})
 
 			It("tells the user it is running in offline mode", func() {
-				Expect(y.Build(buildDir, cacheDir)).To(Succeed())
+				Expect(y.Build(buildDir, cacheDir, false)).To(Succeed())
 				Expect(buffer.String()).To(ContainSubstring("Installing node modules (yarn.lock)"))
 				Expect(buffer.String()).To(ContainSubstring("Found yarn mirror directory " + filepath.Join(buildDir, "npm-packages-offline-cache")))
 				Expect(buffer.String()).To(ContainSubstring("Running yarn in offline mode"))
 			})
 
 			It("runs yarn config", func() {
-				Expect(y.Build(buildDir, cacheDir)).To(Succeed())
+				Expect(y.Build(buildDir, cacheDir, false)).To(Succeed())
 				Expect(yarnConfig).To(Equal(map[string]string{
 					"yarn-offline-mirror":         filepath.Join(buildDir, "npm-packages-offline-cache"),
 					"yarn-offline-mirror-pruning": "false",
@@ -104,7 +104,7 @@ var _ = Describe("Yarn", func() {
 			})
 
 			It("runs yarn install with offline arguments and npm_config_nodedir", func() {
-				Expect(y.Build(buildDir, cacheDir)).To(Succeed())
+				Expect(y.Build(buildDir, cacheDir, false)).To(Succeed())
 				Expect(yarnInstallArgs).To(Equal([]string{
 					"yarn", "install",
 					"--pure-lockfile",
@@ -118,14 +118,14 @@ var _ = Describe("Yarn", func() {
 
 		Context("NO npm-packages-offline-cache directory", func() {
 			It("tells the user it is running in online mode", func() {
-				Expect(y.Build(buildDir, cacheDir)).To(Succeed())
+				Expect(y.Build(buildDir, cacheDir, false)).To(Succeed())
 				Expect(buffer.String()).To(ContainSubstring("Installing node modules (yarn.lock)"))
 				Expect(buffer.String()).To(ContainSubstring("Running yarn in online mode"))
 				Expect(buffer.String()).To(ContainSubstring("To run yarn in offline mode, see: https://yarnpkg.com/blog/2016/11/24/offline-mirror"))
 			})
 
 			It("runs yarn config", func() {
-				Expect(y.Build(buildDir, cacheDir)).To(Succeed())
+				Expect(y.Build(buildDir, cacheDir, false)).To(Succeed())
 				Expect(yarnConfig).To(Equal(map[string]string{
 					"yarn-offline-mirror":         filepath.Join(cacheDir, "npm-packages-offline-cache"),
 					"yarn-offline-mirror-pruning": "true",
@@ -133,7 +133,7 @@ var _ = Describe("Yarn", func() {
 			})
 
 			It("runs yarn install", func() {
-				Expect(y.Build(buildDir, cacheDir)).To(Succeed())
+				Expect(y.Build(buildDir, cacheDir, false)).To(Succeed())
 				Expect(yarnInstallArgs).To(Equal([]string{
 					"yarn", "install",
 					"--pure-lockfile",