chore: backport: fix(aztec-up): installer does not shadow user binaries on PATH (#22902) (#23060)

Backport of #22902 to `backport-to-v4-next-staging`.

## Original change
Native binaries (`forge`, `nargo`, `anvil`, `bb`, …) now live in
`~/.aztec/current/internal-bin` (off `PATH`) and are exposed only via
`aztec-<tool>` symlinks in `~/.aztec/current/bin`. The `aztec`
entrypoint prepends `internal-bin` to its child `PATH` so workflows that
cross-call by basename keep working without leaking those names to the
user's shell.

## Cherry-pick conflict

One conflict during cherry-pick:

- `docs/docs-developers/docs/tutorials/js_tutorials/aave_bridge.md` —
*deleted by us, modified by them.* The file no longer exists on
`backport-to-v4-next-staging`, so the upstream modification has nothing
to apply against.

**Resolution:** dropped the file (matches v4-next state). The first
commit preserves the original cherry-pick result (file restored as
upstream had it) so reviewers can see what would have landed; the second
commit removes it.

No build fixes were needed — the change touches only shell installer
scripts, a standalone TS acceptance test, and docs. Shell syntax checked
with `bash -n` for all modified scripts.

## Commits
1. `fix(aztec-up): ...` — original cherry-pick result, including the
unresolvable file.
2. `fix: resolve cherry-pick conflicts` — drop `aave_bridge.md` to match
the target branch.

ClaudeBox log: https://claudebox.work/s/a57acc5286aef8a6?run=1

Author: vezenovm

aztec-up/README.md

@@ -9,9 +9,14 @@ That is all.
 This will install into `~/.aztec/bin` a collection of scripts to help with running aztec containers, and will update
 the user's `PATH` variable in their shell startup script so they can be found.
 
-- `aztec` - a collection of tools to compile and test contracts, to launch subsystems and interact with the aztec network."
-- `aztec-up` - a tool to install and manage aztec toolchain versions."
-- `aztec-wallet` - our minimalistic CLI wallet"
+- `aztec` - compiles and tests contracts, launches infrastructure subsystems, interacts with the network.
+- `aztec-up` - a version manager for the Aztec toolchain.
+- `aztec-wallet` - a tool for interacting with the Aztec network.
+- `aztec-bb` - the Barretenberg proving backend.
+- `aztec-nargo` - the Noir compiler and simulator.
+- `aztec-forge`, `aztec-cast`, `aztec-anvil`, `aztec-chisel` - the bundled Foundry tools.
+
+Foundry, Noir, and Barretenberg are bundled at the versions `aztec` needs. Your own `forge` / `nargo` / `bb` installs still work under their bare names.
 
 After installed, you can use `aztec-up` to install specific versions.
 

aztec-up/bin/0.0.1/aztec-install

@@ -94,12 +94,14 @@ function title {
   echo -e "Installing version: ${bold}${o}$VERSION${r}"
   echo
   echo -e "This script installs the following and updates your PATH if necessary:"
-  echo -e "  ${bold}${g}nargo${r}          - the noir programming language compiler and simulator."
-  echo -e "  ${bold}${g}noir-profiler${r}  - a profiler for analyzing and visualizing noir programs."
-  echo -e "  ${bold}${g}bb${r}             - the barretenberg proving backend."
   echo -e "  ${bold}${g}aztec${r}          - compiles and tests contracts, interacts with the network."
   echo -e "  ${bold}${g}aztec-up${r}       - installs and manages aztec toolchain versions."
   echo -e "  ${bold}${g}aztec-wallet${r}   - a minimalistic wallet cli."
+  echo -e "  ${bold}${g}aztec-bb${r}       - the barretenberg proving backend."
+  echo -e "  ${bold}${g}aztec-nargo${r}    - the noir compiler and simulator."
+  echo -e "  ${bold}${g}aztec-forge${r}, ${bold}${g}aztec-cast${r}, ${bold}${g}aztec-anvil${r}, ${bold}${g}aztec-chisel${r} - the bundled foundry tools."
+  echo
+  echo -e "Foundry, Noir, and Barretenberg are bundled at the versions ${bold}${g}aztec${r} needs. Your own ${bold}${g}forge${r} / ${bold}${g}nargo${r} / ${bold}${g}bb${r} installs still work under their bare names."
   echo
   read -p "Do you wish to continue? (Y/n) " -n 1 -r
   echo

aztec-up/bin/0.0.1/install

@@ -37,6 +37,12 @@ export FORCE_COLOR=1
 # Version-specific paths
 version_path="$AZTEC_HOME/versions/$VERSION"
 version_bin_path="$version_path/bin"
+# Native binaries (forge/nargo/anvil/...) live here and are NOT on the user's PATH.
+# The aztec wrapper prepends this directory to its child PATH so subprocesses
+# spawned from the aztec workflow (which call sibling tools by basename) resolve
+# to the bundled binaries. User-facing access is only via the aztec-* symlinks
+# in version_bin_path.
+version_internal_bin_path="$version_path/internal-bin"
 
 os="$(uname -s)"
 
@@ -137,7 +143,15 @@ function install_noir {
   set -euo pipefail
 
   if [[ -n ${NARGO:-} ]]; then
-    cp "$NARGO" "$version_bin_path/nargo"
+    cp "$NARGO" "$version_internal_bin_path/nargo"
+    # noir's release build co-locates `noir-profiler` next to `nargo`
+    # (see noir/bootstrap.sh::build_native). Copy it too so the
+    # `aztec-noir-profiler` symlink in install_native_symlinks resolves.
+    local nargo_dir
+    nargo_dir=$(dirname "$NARGO")
+    if [ -f "$nargo_dir/noir-profiler" ]; then
+      cp "$nargo_dir/noir-profiler" "$version_internal_bin_path/noir-profiler"
+    fi
   else
     local noir_version
     noir_version=$(get_version "noir")
@@ -150,13 +164,12 @@ function install_noir {
     # Always install/update noirup
     curl -Ls https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
 
-    # Install noir to temp location and move to version directory
+    # Install noir to temp location and move into internal-bin (off PATH).
     NARGO_HOME="$temp_nargo_home" "$HOME/.nargo/bin/noirup" -v "$noir_version"
 
-    # Move the nargo binary to our version bin directory
-    mv "$temp_nargo_home/bin/nargo" "$version_bin_path/nargo"
+    mv "$temp_nargo_home/bin/nargo" "$version_internal_bin_path/nargo"
     # Also move noir-profiler, needed by `aztec profile flamegraph`
-    mv "$temp_nargo_home/bin/noir-profiler" "$version_bin_path/noir-profiler"
+    mv "$temp_nargo_home/bin/noir-profiler" "$version_internal_bin_path/noir-profiler"
 
     # Cleanup temp directory
     rm -rf "$temp_nargo_home"
@@ -182,10 +195,11 @@ function install_foundry {
   # Install foundry to temp location and move to version directory
   FOUNDRY_DIR="$temp_foundry_dir" timeout 30 "$foundry_home/bin/foundryup" -i "$foundry_version"
 
-  # Move the foundry binaries to our version bin directory
+  # Move the foundry binaries into internal-bin (off PATH); aztec-forge etc.
+  # symlinks in version_bin_path expose them under aztec-prefixed names.
   for binary in forge cast anvil chisel; do
     if [ -f "$temp_foundry_dir/bin/$binary" ]; then
-      mv "$temp_foundry_dir/bin/$binary" "$version_bin_path/$binary"
+      mv "$temp_foundry_dir/bin/$binary" "$version_internal_bin_path/$binary"
     fi
   done
 
@@ -200,32 +214,88 @@ function install_aztec_packages {
   npm install @aztec/aztec@$VERSION @aztec/cli-wallet@$VERSION @aztec/bb.js@$VERSION --prefix "$version_path"
 }
 
-function symlink_aztec_bins {
+# Expose every native tool in internal-bin under an aztec-<tool> symlink in bin.
+# Bare `forge`/`nargo`/etc. are intentionally NOT on PATH so they cannot shadow
+# user-installed tools.
+function install_native_symlinks {
+  set -euo pipefail
+  local tool
+  for tool in forge cast anvil chisel nargo noir-profiler; do
+    if [ ! -e "$version_internal_bin_path/$tool" ]; then
+      echo "Error: expected bundled binary '$tool' missing from $version_internal_bin_path" >&2
+      exit 1
+    fi
+    ln -sfn "../internal-bin/$tool" "$version_bin_path/aztec-$tool"
+  done
+}
+
+# Npm bins are NOT mirrored into internal-bin. The contract for any TS tool
+# that needs to spawn a sibling binary is to resolve an absolute bundled
+# path itself (e.g. via @aztec/bb.js findBbBinary(), or a BB-style env
+# var) -- never by basename + PATH lookup. If you find yourself wanting to
+# add an npm bin to internal-bin so a child process can find it on PATH,
+# fix the caller instead of broadening this list.
+function install_npm_bin_symlinks {
   set -euo pipefail
-  # Populate version_bin_path with symlinks to @aztec-owned bins only. Adding
-  # node_modules/.bin wholesale to PATH would shadow user-installed tools
-  # (jest, tsc, semver, ...) with Aztec's transitive dependencies.
   local npm_bin_dir="$version_path/node_modules/.bin"
   [ -d "$npm_bin_dir" ] || return 0
 
-  local bin_link bin_name target
+  local bin_link bin_name target link_name
   for bin_link in "$npm_bin_dir"/*; do
     [ -L "$bin_link" ] || continue
     target=$(readlink "$bin_link")
     # npm writes relative symlinks like ../@aztec/aztec/... for scoped packages.
     [[ "$target" == ../@aztec/* ]] || continue
     bin_name=$(basename "$bin_link")
-    if [ -e "$version_bin_path/$bin_name" ] && [ ! -L "$version_bin_path/$bin_name" ]; then
-      echo_yellow "refusing to overwrite non-symlink $bin_name; @aztec package bin collides with a hand-installed toolchain binary" >&2
+
+    # `aztec` is a wrapper, written by install_aztec_wrapper.
+    [[ "$bin_name" == "aztec" ]] && continue
+
+    # Already prefixed (e.g. aztec-wallet) keeps its name; everything else gets
+    # renamed to aztec-<orig> so it cannot shadow a user-installed binary.
+    if [[ "$bin_name" == aztec-* ]]; then
+      link_name="$bin_name"
+    else
+      link_name="aztec-$bin_name"
+    fi
+
+    if [ -e "$version_bin_path/$link_name" ] && [ ! -L "$version_bin_path/$link_name" ]; then
+      echo_yellow "refusing to overwrite non-symlink $link_name; @aztec package bin collides with a hand-installed toolchain binary" >&2
       exit 1
     fi
-    ln -sfn "../node_modules/.bin/$bin_name" "$version_bin_path/$bin_name"
+    ln -sfn "../node_modules/.bin/$bin_name" "$version_bin_path/$link_name"
   done
 }
 
+# Wrapper for `aztec`: prepends internal-bin to PATH so the aztec workflow
+# resolves bundled native tools by basename. yarn-project/aztec/scripts/aztec.sh
+# (the npm bin entry of @aztec/aztec) calls bare `nargo` (line 36, in `aztec
+# test`) and bare `anvil` (line 55-56, in `aztec start --local-network`); the
+# TS commands it spawns also fall back to bare `forge` / `nargo` /
+# `noir-profiler` when their respective env vars are unset. The wrapper is
+# kept minimal -- it is the only place we maintain a PATH-based execution
+# context, by design (see install_npm_bin_symlinks for the rationale).
+# BASH_SOURCE[0] (not $0) so PATH-name invocation still resolves internal-bin
+# from the wrapper's actual location.
+function install_aztec_wrapper {
+  set -euo pipefail
+  local wrapper="$version_bin_path/aztec"
+  cat > "$wrapper" <<'EOF'
+#!/usr/bin/env bash
+# Auto-generated by aztec-up. Do not edit.
+set -euo pipefail
+self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+internal_bin="$self_dir/../internal-bin"
+export PATH="$internal_bin:$PATH"
+exec "$self_dir/../node_modules/.bin/aztec" "$@"
+EOF
+  chmod +x "$wrapper"
+}
+
 function main {
-  # Create version directory
+  # Create version directories. bin/ is exposed on PATH; internal-bin/ is not.
   mkdir -p "$version_bin_path"
+  mkdir -p "$version_internal_bin_path"
 
   # Download versions manifest
   echo -n "Installing version manifest... "
@@ -250,14 +320,23 @@ function main {
   dump_fail retry install_foundry
   echo_green "done."
 
+  # Expose native tools as aztec-forge / aztec-nargo / etc.
+  echo -n "Linking aztec native tools... "
+  dump_fail install_native_symlinks
+  echo_green "done."
+
   # Install aztec npm packages
-  echo -n "Installing aztec packages... "
+  echo -n "Installing aztec npm packages... "
   dump_fail retry install_aztec_packages
   echo_green "done."
 
-  # Expose only @aztec-owned bins on PATH (drops transitive npm deps).
+  # Expose @aztec-owned npm bins under aztec-prefixed symlinks. Bare names
+  # (bb, pxe, txe, ...) are intentionally NOT exposed as they would shadow
+  # user-installed tools.
   echo -n "Making aztec commands available... "
-  dump_fail retry symlink_aztec_bins
+  dump_fail install_npm_bin_symlinks
+  # Wrap `aztec` so its subprocesses see internal-bin on PATH.
+  dump_fail install_aztec_wrapper
   echo_green "done."
 }
 

aztec-up/bootstrap.sh

@@ -104,7 +104,7 @@ EOF
 }
 
 function test_cmds {
-  for test in amm_flow bridge_and_claim basic_install counter_contract default_scaffold; do
+  for test in amm_flow bridge_and_claim basic_install counter_contract default_scaffold no_shadow_user_bins; do
     echo "$hash:TIMEOUT=15m aztec-up/scripts/run_test.sh $test"
   done
 }
@@ -234,8 +234,8 @@ function install_on_mac_vm {
     . "\$HOME/.nvm/nvm.sh"
 
     # Verify installation.
-    nargo --version
-    bb --version
+    aztec-nargo --version
+    aztec-bb --version
     aztec --version
 REMOTE_EOF
 }

aztec-up/scripts/run_isolated_test.sh

@@ -98,9 +98,9 @@ EOF
   echo "Version information:"
 
   bash -i -c -e '
-    forge --version
+    aztec-forge --version
     echo
-    nargo --version
+    aztec-nargo --version
     echo
     echo -n "aztec version: "
     aztec --version