From ee58b0efe35114589cc6e3ec1670d732a21d181c Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 08:03:54 +0000
Subject: [PATCH 1/7] fix(bootstrap): add Node.js/yarn prerequisite checks to
 bootstrap scripts

The command-signatures-v2 crate compiles a TypeScript helper at cargo build
time using yarn, which requires Node.js 18.14.1+ and yarn (typically via
corepack). Previously, bootstrap scripts did not verify either was present,
so a fresh checkout would fail partway through cargo build with a confusing
panic instead of at bootstrap time.

Changes:
- script/linux/install_build_deps: add Node.js version check and yarn check
- script/macos/bootstrap: add Node.js version check and yarn check
- WARP.md: document Node.js and yarn as prerequisites

Fixes #9544
---
 WARP.md                         |  4 ++++
 script/linux/install_build_deps | 32 ++++++++++++++++++++++++++++++++
 script/macos/bootstrap          | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+)

diff --git a/WARP.md b/WARP.md
index 9b9fec9f6..8f43bb7f9 100644
--- a/WARP.md
+++ b/WARP.md
@@ -36,6 +36,10 @@ Environment variables:
 - `./script/run-clang-format.py -r --extensions 'c,h,cpp,m' ./crates/warpui/src/ ./app/src/` - Format C/C++/Obj-C code
 - `find . -name "*.wgsl" -exec wgslfmt --check {} +` - Check WGSL shader formatting
 
+### Prerequisites
+- **Node.js 18.14.1+** — Required by the `command-signatures-v2` crate, which compiles a TypeScript helper at build time using yarn.
+- **yarn** — Required by the `command-signatures-v2` build script. Enable via `corepack enable` after installing Node.js.
+
 ### Platform Setup
 - `./script/bootstrap` - Platform-specific setup (calls platform-specific bootstrap scripts)
 - `./script/install_cargo_build_deps` - Install Cargo build dependencies
diff --git a/script/linux/install_build_deps b/script/linux/install_build_deps
index b9b66f8e7..2ecbf5f7b 100755
--- a/script/linux/install_build_deps
+++ b/script/linux/install_build_deps
@@ -53,6 +53,38 @@ else
   echo -e "⚠️  ${red}Unknown Linux distribution; necessary build dependencies may not be installed!${reset}"
 fi
 
+# Check for Node.js (required by command-signatures-v2 crate).
+# The build.rs in that crate compiles a TypeScript helper using yarn,
+# which requires Node.js 18.14.1+ and yarn (typically via corepack).
+REQUIRED_NODE_VERSION="18.14.1"
+if ! command -v node &>/dev/null; then
+  echo -e "${red}Error: Node.js is not installed.${reset}"
+  echo "Node.js $REQUIRED_NODE_VERSION+ is required to build the command-signatures-v2 crate."
+  echo "Install it via your system package manager, nvm, fnm, or volta:"
+  echo "  https://nodejs.org/en/download"
+  exit 1
+fi
+
+NODE_VERSION="$(node --version | sed 's/^v//')"
+if [[ "$(printf '%s\n' "$REQUIRED_NODE_VERSION" "$NODE_VERSION" | sort -V | head -n1)" != "$REQUIRED_NODE_VERSION" ]]; then
+  echo -e "${red}Error: Node.js $NODE_VERSION is too old.${reset}"
+  echo "Node.js $REQUIRED_NODE_VERSION+ is required. Current version: $NODE_VERSION"
+  echo "Upgrade via your system package manager, nvm, fnm, or volta."
+  exit 1
+fi
+
+# Check for yarn (required by command-signatures-v2 crate).
+# yarn is typically enabled via `corepack enable` after installing Node.js.
+if ! command -v yarn &>/dev/null; then
+  echo -e "${red}Error: yarn is not installed.${reset}"
+  echo "yarn is required to build the command-signatures-v2 crate."
+  echo "Enable it via corepack (ships with Node.js):"
+  echo "  corepack enable"
+  exit 1
+fi
+
+echo "✅ Node.js $(node --version) and yarn $(yarn --version) detected."
+
 # Install Rust.
 "$PWD"/script/install_rust
 
diff --git a/script/macos/bootstrap b/script/macos/bootstrap
index f146e4b1b..46ca2643d 100755
--- a/script/macos/bootstrap
+++ b/script/macos/bootstrap
@@ -29,6 +29,39 @@ if ! command -v cargo; then
     exit 1
 fi
 
+# Check for Node.js (required by command-signatures-v2 crate).
+# The build.rs in that crate compiles a TypeScript helper using yarn,
+# which requires Node.js 18.14.1+ and yarn (typically via corepack).
+REQUIRED_NODE_VERSION="18.14.1"
+if ! command -v node >/dev/null 2>&1; then
+    echo "Error: Node.js is not installed."
+    echo "Node.js $REQUIRED_NODE_VERSION+ is required to build the command-signatures-v2 crate."
+    echo "Install it via: brew install node"
+    echo "  or use a version manager like nvm, fnm, or volta."
+    exit 1
+fi
+
+NODE_VERSION="$(node --version | sed 's/^v//')"
+# Use awk for version comparison since sh doesn't support sort -V
+if ! echo "$REQUIRED_NODE_VERSION" "$NODE_VERSION" | awk '{if ($2 < $1) exit 1; else exit 0}'; then
+    echo "Error: Node.js $NODE_VERSION is too old."
+    echo "Node.js $REQUIRED_NODE_VERSION+ is required."
+    echo "Upgrade via: brew upgrade node"
+    exit 1
+fi
+
+# Check for yarn (required by command-signatures-v2 crate).
+# yarn is typically enabled via `corepack enable` after installing Node.js.
+if ! command -v yarn >/dev/null 2>&1; then
+    echo "Error: yarn is not installed."
+    echo "yarn is required to build the command-signatures-v2 crate."
+    echo "Enable it via corepack (ships with Node.js):"
+    echo "  corepack enable"
+    exit 1
+fi
+
+echo "✅ Node.js $(node --version) and yarn $(yarn --version) detected."
+
 # Install various binaries through cargo.
 "$PWD"/script/install_cargo_test_deps
 "$PWD"/script/install_cargo_release_deps

From 6ec437240b246e81cc21ded00270b96e5e90c892 Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 08:52:20 +0000
Subject: [PATCH 2/7] fix(bootstrap): use proper semantic version comparison
 for Node.js check

Address Oz review feedback: the previous awk-based comparison used
lexicographic ordering, which incorrectly allowed versions like 18.9.0
to pass the >=18.14.1 gate (since "9" > "1" lexicographically).

Now splits version into major.minor.patch components and compares each
numerically.
---
 script/macos/bootstrap | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/script/macos/bootstrap b/script/macos/bootstrap
index 46ca2643d..6afe825a1 100755
--- a/script/macos/bootstrap
+++ b/script/macos/bootstrap
@@ -42,8 +42,18 @@ if ! command -v node >/dev/null 2>&1; then
 fi
 
 NODE_VERSION="$(node --version | sed 's/^v//')"
-# Use awk for version comparison since sh doesn't support sort -V
-if ! echo "$REQUIRED_NODE_VERSION" "$NODE_VERSION" | awk '{if ($2 < $1) exit 1; else exit 0}'; then
+# Compare semantic versions properly (not lexicographically).
+# Split into major.minor.patch and compare each component.
+node_major="$(echo "$NODE_VERSION" | cut -d. -f1)"
+node_minor="$(echo "$NODE_VERSION" | cut -d. -f2)"
+node_patch="$(echo "$NODE_VERSION" | cut -d. -f3)"
+req_major="$(echo "$REQUIRED_NODE_VERSION" | cut -d. -f1)"
+req_minor="$(echo "$REQUIRED_NODE_VERSION" | cut -d. -f2)"
+req_patch="$(echo "$REQUIRED_NODE_VERSION" | cut -d. -f3)"
+
+if [ "$node_major" -lt "$req_major" ] || \
+   { [ "$node_major" -eq "$req_major" ] && [ "$node_minor" -lt "$req_minor" ]; } || \
+   { [ "$node_major" -eq "$req_major" ] && [ "$node_minor" -eq "$req_minor" ] && [ "$node_patch" -lt "$req_patch" ]; }; then
     echo "Error: Node.js $NODE_VERSION is too old."
     echo "Node.js $REQUIRED_NODE_VERSION+ is required."
     echo "Upgrade via: brew upgrade node"

From e8b99ade7fccce3ed34ee0e9549db6ba946d5856 Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 09:05:22 +0000
Subject: [PATCH 3/7] fix(bootstrap): verify yarn version is 4+ (Corepack), not
 1.x (Homebrew)

Address Oz review feedback: the previous yarn check accepted any yarn
executable on PATH, including Yarn 1 installed via Homebrew. The crate
requires Yarn 4 via Corepack.

Now checks yarn major version and rejects Yarn 1.x with clear guidance
to uninstall Homebrew yarn and enable Corepack.
---
 script/linux/install_build_deps | 14 ++++++++++++++
 script/macos/bootstrap          | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/script/linux/install_build_deps b/script/linux/install_build_deps
index 2ecbf5f7b..73e6b0736 100755
--- a/script/linux/install_build_deps
+++ b/script/linux/install_build_deps
@@ -74,6 +74,7 @@ if [[ "$(printf '%s\n' "$REQUIRED_NODE_VERSION" "$NODE_VERSION" | sort -V | head
 fi
 
 # Check for yarn (required by command-signatures-v2 crate).
+# The crate uses Yarn 4 via Corepack, not Yarn 1 from Homebrew.
 # yarn is typically enabled via `corepack enable` after installing Node.js.
 if ! command -v yarn &>/dev/null; then
   echo -e "${red}Error: yarn is not installed.${reset}"
@@ -83,6 +84,19 @@ if ! command -v yarn &>/dev/null; then
   exit 1
 fi
 
+# Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
+YARN_VERSION="$(yarn --version 2>/dev/null)"
+YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
+if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
+  echo -e "${red}Error: yarn $YARN_VERSION detected, but Yarn 4+ is required.${reset}"
+  echo "The command-signatures-v2 crate requires Yarn 4 via Corepack."
+  echo "If you have yarn installed via Homebrew, remove it first:"
+  echo "  brew uninstall yarn"
+  echo "Then enable Corepack:"
+  echo "  corepack enable"
+  exit 1
+fi
+
 echo "✅ Node.js $(node --version) and yarn $(yarn --version) detected."
 
 # Install Rust.
diff --git a/script/macos/bootstrap b/script/macos/bootstrap
index 6afe825a1..7c1fddce4 100755
--- a/script/macos/bootstrap
+++ b/script/macos/bootstrap
@@ -61,6 +61,7 @@ if [ "$node_major" -lt "$req_major" ] || \
 fi
 
 # Check for yarn (required by command-signatures-v2 crate).
+# The crate uses Yarn 4 via Corepack, not Yarn 1 from Homebrew.
 # yarn is typically enabled via `corepack enable` after installing Node.js.
 if ! command -v yarn >/dev/null 2>&1; then
     echo "Error: yarn is not installed."
@@ -70,6 +71,19 @@ if ! command -v yarn >/dev/null 2>&1; then
     exit 1
 fi
 
+# Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
+YARN_VERSION="$(yarn --version 2>/dev/null)"
+YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
+if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
+    echo "Error: yarn $YARN_VERSION detected, but Yarn 4+ is required."
+    echo "The command-signatures-v2 crate requires Yarn 4 via Corepack."
+    echo "If you have yarn installed via Homebrew, remove it first:"
+    echo "  brew uninstall yarn"
+    echo "Then enable Corepack:"
+    echo "  corepack enable"
+    exit 1
+fi
+
 echo "✅ Node.js $(node --version) and yarn $(yarn --version) detected."
 
 # Install various binaries through cargo.

From 99db41e885088101caeafe1eed3e00f06570ca93 Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 09:20:52 +0000
Subject: [PATCH 4/7] fix(build): check Yarn version from js crate dir, not
 repo root

Corepack reads packageManager from the nearest package.json. Running
yarn --version from repo root could report a different version than
what build.rs uses, since it runs from crates/command-signatures-v2/js.

Change the check to cd into the js subdir before version check so it
matches the actual build environment.
---
 script/linux/install_build_deps | 6 ++++--
 script/macos/bootstrap          | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/script/linux/install_build_deps b/script/linux/install_build_deps
index 73e6b0736..5f66bf449 100755
--- a/script/linux/install_build_deps
+++ b/script/linux/install_build_deps
@@ -85,7 +85,9 @@ if ! command -v yarn &>/dev/null; then
 fi
 
 # Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
-YARN_VERSION="$(yarn --version 2>/dev/null)"
+# Check from the js crate directory where Corepack reads packageManager.
+JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
+YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"
 YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
 if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
   echo -e "${red}Error: yarn $YARN_VERSION detected, but Yarn 4+ is required.${reset}"
@@ -97,7 +99,7 @@ if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
   exit 1
 fi
 
-echo "✅ Node.js $(node --version) and yarn $(yarn --version) detected."
+echo "✅ Node.js $(node --version) and yarn $YARN_VERSION detected."
 
 # Install Rust.
 "$PWD"/script/install_rust
diff --git a/script/macos/bootstrap b/script/macos/bootstrap
index 7c1fddce4..cbe931c3d 100755
--- a/script/macos/bootstrap
+++ b/script/macos/bootstrap
@@ -72,7 +72,9 @@ if ! command -v yarn >/dev/null 2>&1; then
 fi
 
 # Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
-YARN_VERSION="$(yarn --version 2>/dev/null)"
+# Check from the js crate directory where Corepack reads packageManager.
+JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
+YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"
 YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
 if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
     echo "Error: yarn $YARN_VERSION detected, but Yarn 4+ is required."
@@ -84,7 +86,7 @@ if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
     exit 1
 fi
 
-echo "✅ Node.js $(node --version) and yarn $(yarn --version) detected."
+echo "✅ Node.js $(node --version) and yarn $YARN_VERSION detected."
 
 # Install various binaries through cargo.
 "$PWD"/script/install_cargo_test_deps

From b299d8b06c7ea0f1a882ac0607729d95720cab90 Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 09:29:09 +0000
Subject: [PATCH 5/7] fix(build): wrap yarn version check for set -e, clarify
 Yarn 4+ in docs

Wrap the yarn --version subshell in 'if !' so that a Corepack or Yarn
execution failure prints actionable guidance instead of silently exiting
under set -e. Also update WARP.md to explicitly state Yarn 4+ via Corepack
and warn against Homebrew's Yarn 1.x.
---
 WARP.md                         | 2 +-
 script/linux/install_build_deps | 7 ++++++-
 script/macos/bootstrap          | 7 ++++++-
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/WARP.md b/WARP.md
index 8f43bb7f9..7f1c5232d 100644
--- a/WARP.md
+++ b/WARP.md
@@ -38,7 +38,7 @@ Environment variables:
 
 ### Prerequisites
 - **Node.js 18.14.1+** — Required by the `command-signatures-v2` crate, which compiles a TypeScript helper at build time using yarn.
-- **yarn** — Required by the `command-signatures-v2` build script. Enable via `corepack enable` after installing Node.js.
+- **Yarn 4+ via Corepack** — Required by the `command-signatures-v2` build script. Enable via `corepack enable` after installing Node.js; avoid Yarn 1.x from package managers such as Homebrew.
 
 ### Platform Setup
 - `./script/bootstrap` - Platform-specific setup (calls platform-specific bootstrap scripts)
diff --git a/script/linux/install_build_deps b/script/linux/install_build_deps
index 5f66bf449..8daf9d750 100755
--- a/script/linux/install_build_deps
+++ b/script/linux/install_build_deps
@@ -87,7 +87,12 @@ fi
 # Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
 # Check from the js crate directory where Corepack reads packageManager.
 JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
-YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"
+if ! YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"; then
+  echo -e "${red}Error: Could not determine yarn version from $JS_CRATE_DIR.${reset}"
+  echo "Ensure yarn is installed and Corepack is enabled:"
+  echo "  corepack enable"
+  exit 1
+fi
 YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
 if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
   echo -e "${red}Error: yarn $YARN_VERSION detected, but Yarn 4+ is required.${reset}"
diff --git a/script/macos/bootstrap b/script/macos/bootstrap
index cbe931c3d..2e87d81e3 100755
--- a/script/macos/bootstrap
+++ b/script/macos/bootstrap
@@ -74,7 +74,12 @@ fi
 # Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
 # Check from the js crate directory where Corepack reads packageManager.
 JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
-YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"
+if ! YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"; then
+    echo "Error: Could not determine yarn version from $JS_CRATE_DIR."
+    echo "Ensure yarn is installed and Corepack is enabled:"
+    echo "  corepack enable"
+    exit 1
+fi
 YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
 if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
     echo "Error: yarn $YARN_VERSION detected, but Yarn 4+ is required."

From 60de89c1e2278d4632bb3c01ca66c10a7855ec7b Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 09:40:01 +0000
Subject: [PATCH 6/7] fix(bootstrap): move Node/Yarn checks to
 script/linux/bootstrap entry point
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Oz flagged that the Node/Yarn checks were inside install_build_deps,
which is not directly called by script/linux/bootstrap — it was only
reached indirectly via install_test_deps → install_runtime_deps.

Move the checks to the top of script/linux/bootstrap (after apt update,
before install_test_deps) so they are visible at the entry point and
match the macOS bootstrap structure.
---
 script/linux/bootstrap          | 50 +++++++++++++++++++++++++++++++
 script/linux/install_build_deps | 53 ---------------------------------
 2 files changed, 50 insertions(+), 53 deletions(-)

diff --git a/script/linux/bootstrap b/script/linux/bootstrap
index daf005496..087d164a8 100755
--- a/script/linux/bootstrap
+++ b/script/linux/bootstrap
@@ -6,6 +6,56 @@ set -e
 # don't do it (to avoid doing it more than once).
 sudo apt update -y
 
+# Check for Node.js and yarn (required by command-signatures-v2 crate).
+# The build.rs in that crate compiles a TypeScript helper using yarn,
+# which requires Node.js 18.14.1+ and Yarn 4+ via Corepack.
+REQUIRED_NODE_VERSION="18.14.1"
+if ! command -v node &>/dev/null; then
+  echo -e "\033[0;31mError: Node.js is not installed.\033[0m"
+  echo "Node.js $REQUIRED_NODE_VERSION+ is required to build the command-signatures-v2 crate."
+  echo "Install it via your system package manager, nvm, fnm, or volta:"
+  echo "  https://nodejs.org/en/download"
+  exit 1
+fi
+
+NODE_VERSION="$(node --version | sed 's/^v//')"
+if [[ "$(printf '%s\n' "$REQUIRED_NODE_VERSION" "$NODE_VERSION" | sort -V | head -n1)" != "$REQUIRED_NODE_VERSION" ]]; then
+  echo -e "\033[0;31mError: Node.js $NODE_VERSION is too old.\033[0m"
+  echo "Node.js $REQUIRED_NODE_VERSION+ is required. Current version: $NODE_VERSION"
+  echo "Upgrade via your system package manager, nvm, fnm, or volta."
+  exit 1
+fi
+
+if ! command -v yarn &>/dev/null; then
+  echo -e "\033[0;31mError: yarn is not installed.\033[0m"
+  echo "yarn is required to build the command-signatures-v2 crate."
+  echo "Enable it via corepack (ships with Node.js):"
+  echo "  corepack enable"
+  exit 1
+fi
+
+# Verify yarn version is 4+ (Corepack-managed), not 1.x (Homebrew).
+# Check from the js crate directory where Corepack reads packageManager.
+JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
+if ! YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"; then
+  echo -e "\033[0;31mError: Could not determine yarn version from $JS_CRATE_DIR.\033[0m"
+  echo "Ensure yarn is installed and Corepack is enabled:"
+  echo "  corepack enable"
+  exit 1
+fi
+YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
+if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
+  echo -e "\033[0;31mError: yarn $YARN_VERSION detected, but Yarn 4+ is required.\033[0m"
+  echo "The command-signatures-v2 crate requires Yarn 4 via Corepack."
+  echo "If you have yarn installed via Homebrew, remove it first:"
+  echo "  brew uninstall yarn"
+  echo "Then enable Corepack:"
+  echo "  corepack enable"
+  exit 1
+fi
+
+echo "✅ Node.js $(node --version) and yarn $YARN_VERSION detected."
+
 # Install all dependencies needed to build, run, and test Warp.
 "$PWD"/script/linux/install_test_deps
 
diff --git a/script/linux/install_build_deps b/script/linux/install_build_deps
index 8daf9d750..b9b66f8e7 100755
--- a/script/linux/install_build_deps
+++ b/script/linux/install_build_deps
@@ -53,59 +53,6 @@ else
   echo -e "⚠️  ${red}Unknown Linux distribution; necessary build dependencies may not be installed!${reset}"
 fi
 
-# Check for Node.js (required by command-signatures-v2 crate).
-# The build.rs in that crate compiles a TypeScript helper using yarn,
-# which requires Node.js 18.14.1+ and yarn (typically via corepack).
-REQUIRED_NODE_VERSION="18.14.1"
-if ! command -v node &>/dev/null; then
-  echo -e "${red}Error: Node.js is not installed.${reset}"
-  echo "Node.js $REQUIRED_NODE_VERSION+ is required to build the command-signatures-v2 crate."
-  echo "Install it via your system package manager, nvm, fnm, or volta:"
-  echo "  https://nodejs.org/en/download"
-  exit 1
-fi
-
-NODE_VERSION="$(node --version | sed 's/^v//')"
-if [[ "$(printf '%s\n' "$REQUIRED_NODE_VERSION" "$NODE_VERSION" | sort -V | head -n1)" != "$REQUIRED_NODE_VERSION" ]]; then
-  echo -e "${red}Error: Node.js $NODE_VERSION is too old.${reset}"
-  echo "Node.js $REQUIRED_NODE_VERSION+ is required. Current version: $NODE_VERSION"
-  echo "Upgrade via your system package manager, nvm, fnm, or volta."
-  exit 1
-fi
-
-# Check for yarn (required by command-signatures-v2 crate).
-# The crate uses Yarn 4 via Corepack, not Yarn 1 from Homebrew.
-# yarn is typically enabled via `corepack enable` after installing Node.js.
-if ! command -v yarn &>/dev/null; then
-  echo -e "${red}Error: yarn is not installed.${reset}"
-  echo "yarn is required to build the command-signatures-v2 crate."
-  echo "Enable it via corepack (ships with Node.js):"
-  echo "  corepack enable"
-  exit 1
-fi
-
-# Verify yarn version is 4.x (Corepack-managed), not 1.x (Homebrew).
-# Check from the js crate directory where Corepack reads packageManager.
-JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
-if ! YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"; then
-  echo -e "${red}Error: Could not determine yarn version from $JS_CRATE_DIR.${reset}"
-  echo "Ensure yarn is installed and Corepack is enabled:"
-  echo "  corepack enable"
-  exit 1
-fi
-YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
-if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
-  echo -e "${red}Error: yarn $YARN_VERSION detected, but Yarn 4+ is required.${reset}"
-  echo "The command-signatures-v2 crate requires Yarn 4 via Corepack."
-  echo "If you have yarn installed via Homebrew, remove it first:"
-  echo "  brew uninstall yarn"
-  echo "Then enable Corepack:"
-  echo "  corepack enable"
-  exit 1
-fi
-
-echo "✅ Node.js $(node --version) and yarn $YARN_VERSION detected."
-
 # Install Rust.
 "$PWD"/script/install_rust
 

From f9c0698c66c974d4b50a8e699307b08d86812282 Mon Sep 17 00:00:00 2001
From: Jiahao Ren <gl6532575@gmail.com>
Date: Thu, 30 Apr 2026 11:23:43 +0000
Subject: [PATCH 7/7] fix: add Node.js/Yarn prerequisite checks to
 install_build_deps

The install_build_deps script was missing Node.js and Yarn version
checks, unlike the macOS bootstrap and Linux bootstrap entry point.
Developers running install_build_deps directly could hit opaque
build failures from the command-signatures-v2 crate.

Add the same prerequisite validation (Node 18.14.1+, Yarn 4+ via
Corepack) with safe error handling under set -e using the if ! pattern.
---
 script/linux/install_build_deps | 64 +++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/script/linux/install_build_deps b/script/linux/install_build_deps
index b9b66f8e7..51a28529d 100755
--- a/script/linux/install_build_deps
+++ b/script/linux/install_build_deps
@@ -53,6 +53,70 @@ else
   echo -e "⚠️  ${red}Unknown Linux distribution; necessary build dependencies may not be installed!${reset}"
 fi
 
+# Check for Node.js (required by command-signatures-v2 crate).
+# The build.rs in that crate compiles a TypeScript helper using yarn,
+# which requires Node.js 18.14.1+ and yarn (typically via corepack).
+REQUIRED_NODE_VERSION="18.14.1"
+if ! command -v node >/dev/null 2>&1; then
+    echo "Error: Node.js is not installed."
+    echo "Node.js $REQUIRED_NODE_VERSION+ is required to build the command-signatures-v2 crate."
+    echo "Install it via: curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs"
+    echo "  or use a version manager like nvm, fnm, or volta."
+    exit 1
+fi
+
+NODE_VERSION="$(node --version | sed 's/^v//')"
+node_major="$(echo "$NODE_VERSION" | cut -d. -f1)"
+node_minor="$(echo "$NODE_VERSION" | cut -d. -f2)"
+node_patch="$(echo "$NODE_VERSION" | cut -d. -f3)"
+req_major="$(echo "$REQUIRED_NODE_VERSION" | cut -d. -f1)"
+req_minor="$(echo "$REQUIRED_NODE_VERSION" | cut -d. -f2)"
+req_patch="$(echo "$REQUIRED_NODE_VERSION" | cut -d. -f3)"
+
+if [ "$node_major" -lt "$req_major" ] || \
+   { [ "$node_major" -eq "$req_major" ] && [ "$node_minor" -lt "$req_minor" ]; } || \
+   { [ "$node_major" -eq "$req_major" ] && [ "$node_minor" -eq "$req_minor" ] && [ "$node_patch" -lt "$req_patch" ]; }; then
+    echo "Error: Node.js $NODE_VERSION is too old."
+    echo "Node.js $REQUIRED_NODE_VERSION+ is required."
+    echo "Upgrade via your system package manager or version manager."
+    exit 1
+fi
+
+# Check for yarn (required by command-signatures-v2 crate).
+# The crate uses Yarn 4 via Corepack, not Yarn 1 from system packages.
+# yarn is typically enabled via `corepack enable` after installing Node.js.
+if ! command -v yarn >/dev/null 2>&1; then
+    echo "Error: yarn is not installed."
+    echo "yarn is required to build the command-signatures-v2 crate."
+    echo "Enable it via corepack (ships with Node.js):"
+    echo "  corepack enable"
+    exit 1
+fi
+
+# Verify yarn version is 4.x (Corepack-managed), not 1.x (system package).
+# Check from the js crate directory where Corepack reads packageManager.
+# Wrap in `if !` so that a Corepack/yarn failure shows guidance instead of
+# exiting silently under `set -e`.
+JS_CRATE_DIR="$PWD/crates/command-signatures-v2/js"
+if ! YARN_VERSION="$(cd "$JS_CRATE_DIR" && yarn --version 2>/dev/null)"; then
+    echo "Error: Could not determine yarn version from $JS_CRATE_DIR."
+    echo "Ensure yarn is installed and Corepack is enabled:"
+    echo "  corepack enable"
+    exit 1
+fi
+YARN_MAJOR="$(echo "$YARN_VERSION" | cut -d. -f1)"
+if [ "$YARN_MAJOR" -lt 4 ] 2>/dev/null; then
+    echo "Error: yarn $YARN_VERSION detected, but Yarn 4+ is required."
+    echo "The command-signatures-v2 crate requires Yarn 4 via Corepack."
+    echo "If you have yarn installed via a system package, remove it first:"
+    echo "  sudo apt-get remove yarn  # or equivalent for your distro"
+    echo "Then enable Corepack:"
+    echo "  corepack enable"
+    exit 1
+fi
+
+echo "✅ Node.js $(node --version) and yarn $YARN_VERSION detected."
+
 # Install Rust.
 "$PWD"/script/install_rust