@osfactory/har 0.49.2 → 0.50.0

package/dist/templates/har-boilerplate/provision-toolchain.sh

@@ -27,6 +27,119 @@ pt_log() {
   fi
 }
 
+# ── Node package manager helpers ──────────────────────────────────────────────
+# Mirrored verbatim in harness.env and provision-toolchain.sh so a sourcing
+# script and the provisioning subprocess resolve the same tool.
+
+# Package managers HAR can drive, in fallback preference order.
+HAR_NODE_PACKAGE_MANAGERS="npm bun pnpm yarn"
+
+# Package manager the repo declares: an explicit HARNESS_NODE_PACKAGE_MANAGER
+# wins, then package.json "packageManager", then the lockfile. Empty when the
+# repo says nothing.
+har_node_declared_package_manager() {
+  local dir="${1:-.}"
+
+  if [ -n "${HARNESS_NODE_PACKAGE_MANAGER:-}" ]; then
+    echo "$HARNESS_NODE_PACKAGE_MANAGER"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then
+    local field
+    field="$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([a-z]*\)@.*/\1/p' "$dir/package.json" | head -1)"
+    if [ -n "$field" ]; then
+      echo "$field"
+      return
+    fi
+  fi
+  if [ -f "$dir/bun.lock" ] || [ -f "$dir/bun.lockb" ]; then echo bun; return; fi
+  if [ -f "$dir/pnpm-lock.yaml" ]; then echo pnpm; return; fi
+  if [ -f "$dir/yarn.lock" ]; then echo yarn; return; fi
+  if [ -f "$dir/package-lock.json" ]; then echo npm; return; fi
+  echo ""
+}
+
+# Package manager to actually run. A manager the repo declares but this machine
+# lacks falls back to one that is installed, so a repo pinned to npm still
+# provisions on a bun-only machine (and the reverse).
+har_node_package_manager() {
+  local dir="${1:-.}"
+  local declared
+  declared="$(har_node_declared_package_manager "$dir")"
+
+  if [ -n "$declared" ] && command -v "$declared" >/dev/null 2>&1; then
+    echo "$declared"
+    return
+  fi
+
+  local candidate
+  for candidate in $HAR_NODE_PACKAGE_MANAGERS; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return
+    fi
+  done
+
+  echo "${declared:-npm}"
+}
+
+# Lockfile a manager writes, so a substitute install can clean up after itself.
+har_node_lockfile() {
+  case "$1" in
+    bun) echo "bun.lock" ;;
+    npm) echo "package-lock.json" ;;
+    pnpm) echo "pnpm-lock.yaml" ;;
+    yarn) echo "yarn.lock" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Install dependencies in a directory. When a substitute manager stands in for
+# the one the repo declares, any lockfile it creates is removed afterwards:
+# provisioning must not migrate the repo to a different package manager.
+# (bun writes bun.lock even under --no-save, so the flags alone are not enough.)
+har_node_install() {
+  local dir="$1"
+  local manager="$2"
+  local declared="${3:-}"
+  local substituting=false
+  local lockfile=""
+  local had_lockfile=false
+
+  if [ -n "$declared" ] && [ "$declared" != "$manager" ]; then
+    substituting=true
+    lockfile="$(har_node_lockfile "$manager")"
+    if [ -n "$lockfile" ] && [ -e "$dir/$lockfile" ]; then
+      had_lockfile=true
+    fi
+  fi
+
+  local code=0
+  (cd "$dir" && "$manager" install --silent) || code=$?
+
+  if [ "$substituting" = true ] && [ "$had_lockfile" = false ] && [ -n "$lockfile" ]; then
+    rm -f "$dir/$lockfile"
+    [ "$manager" = "bun" ] && rm -f "$dir/bun.lockb"
+  fi
+  return $code
+}
+
+# Package runner (npx equivalent) for one-off CLIs such as pm2, including the
+# flag that keeps it non-interactive. Takes a manager name, or none to resolve
+# from the environment and PATH.
+har_pkg_exec() {
+  case "${1:-${HARNESS_NODE_PACKAGE_MANAGER:-}}" in
+    bun) echo "bunx"; return ;;
+    pnpm) echo "pnpm dlx"; return ;;
+    yarn) echo "yarn dlx"; return ;;
+    npm) echo "npx --yes"; return ;;
+  esac
+  if command -v npx >/dev/null 2>&1; then echo "npx --yes"; return; fi
+  if command -v bunx >/dev/null 2>&1; then echo "bunx"; return; fi
+  if command -v pnpm >/dev/null 2>&1; then echo "pnpm dlx"; return; fi
+  echo "npx --yes"
+}
+
 append_env() {
   local key="$1"
   local value="$2"
@@ -81,32 +194,37 @@ run_install_cmd() {
 
 provision_node() {
   local dir="$1"
-  local npm_bin="npm"
   local node_bin="node"
+  local pkg_manager declared_manager
+  declared_manager="$(har_node_declared_package_manager "$dir")"
+  pkg_manager="$(har_node_package_manager "$dir")"
+
+  if [ -n "$declared_manager" ] && [ "$declared_manager" != "$pkg_manager" ]; then
+    pt_log "Repo declares ${declared_manager}, which is not on PATH — installing with ${pkg_manager} and leaving the lockfile untouched."
+  fi
 
   if ! run_install_cmd "$dir"; then
-    pt_log "Installing Node dependencies..."
-    if [ -f "$dir/pnpm-lock.yaml" ] && command -v pnpm >/dev/null 2>&1; then
-      (cd "$dir" && pnpm install --silent)
-      npm_bin="pnpm"
-    elif [ -f "$dir/yarn.lock" ] && command -v yarn >/dev/null 2>&1; then
-      (cd "$dir" && yarn install --silent)
-      npm_bin="yarn"
-    else
-      (cd "$dir" && npm install --silent)
-    fi
+    pt_log "Installing Node dependencies with ${pkg_manager}..."
+    har_node_install "$dir" "$pkg_manager" "$declared_manager"
   fi
 
   if command -v node >/dev/null 2>&1; then
     node_bin="$(command -v node)"
+  elif [ "$pkg_manager" = "bun" ]; then
+    # bun-only machine: bun runs the `node -e` snippets verify.sh relies on.
+    node_bin="$(command -v bun)"
   fi
-  if [ "$npm_bin" = "npm" ] && command -v npm >/dev/null 2>&1; then
-    npm_bin="$(command -v npm)"
+
+  local npm_bin="$pkg_manager"
+  if command -v "$pkg_manager" >/dev/null 2>&1; then
+    npm_bin="$(command -v "$pkg_manager")"
   fi
 
   append_env "HARNESS_ECOSYSTEM" "node"
   append_env "NODE_BIN" "$node_bin"
   append_env "NPM_BIN" "$npm_bin"
+  append_env "HARNESS_NODE_PACKAGE_MANAGER" "$pkg_manager"
+  append_env "HARNESS_PKG_EXEC" "$(har_pkg_exec "$pkg_manager")"
   append_path_prefix "$dir/node_modules/.bin"
 }
 
@@ -252,8 +370,11 @@ provision_monorepo_root() {
   [ -n "$HAR_WORKTREE_DIR" ] || return 0
   [ -f "$HAR_WORKTREE_DIR/package.json" ] || return 0
   [ -d "$HAR_WORKTREE_DIR/node_modules" ] && return 0
-  pt_log "Installing monorepo root dependencies in $HAR_WORKTREE_DIR..."
-  (cd "$HAR_WORKTREE_DIR" && npm install --silent)
+  local pkg_manager
+  pkg_manager="$(har_node_package_manager "$HAR_WORKTREE_DIR")"
+  pt_log "Installing monorepo root dependencies in $HAR_WORKTREE_DIR with ${pkg_manager}..."
+  har_node_install "$HAR_WORKTREE_DIR" "$pkg_manager" \
+    "$(har_node_declared_package_manager "$HAR_WORKTREE_DIR")"
 }
 
 provision_ecosystem() {

package/dist/templates/har-boilerplate/setup-infra.sh

@@ -165,7 +165,7 @@ fi
 SHARED_ECOSYSTEM="$SCRIPT_DIR/ecosystem.shared.config.cjs"
 if [ -f "$SHARED_ECOSYSTEM" ]; then
   log "Starting shared app services from ecosystem.shared.config.cjs..."
-  (cd "$REPO_ROOT" && npx --yes pm2 startOrReload "$SHARED_ECOSYSTEM" >/dev/null)
+  (cd "$REPO_ROOT" && $(har_pkg_exec) pm2 startOrReload "$SHARED_ECOSYSTEM" >/dev/null)
   log "Shared app services running (pm2 ls | grep har-${HARNESS_PROJECT_NAME}-shared-)."
 fi
 

package/dist/templates/har-boilerplate/teardown.sh

@@ -41,7 +41,7 @@ fi
 [ -n "$WORKTREE_PATH" ] || WORKTREE_PATH="$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${AGENT_ID}"
 
 PM2_REGEX="$(har_pm2_delete_regex "$AGENT_ID")"
-npx --yes pm2 delete "$PM2_REGEX" 2>/dev/null || true
+$(har_pkg_exec) pm2 delete "$PM2_REGEX" 2>/dev/null || true
 echo "✓ Stopped PM2 processes"
 
 if har_infra_enabled db; then

package/dist/templates/har-boilerplate-cli/agent-slot.sh

@@ -164,7 +164,7 @@ har_check_foreign_pm2() {
   local agent_id="$1"
   local pm2_raw
   har_harness_uses_pm2 || return 0
-  pm2_raw="$(npx --yes pm2 jlist 2>/dev/null || true)"
+  pm2_raw="$($(har_pkg_exec) pm2 jlist 2>/dev/null || true)"
   [ -n "$pm2_raw" ] || return 0
   set +e
   echo "$pm2_raw" | node -e "

package/dist/templates/har-boilerplate-cli/harness.env

@@ -23,6 +23,10 @@ export HARNESS_AGENT_SLOT_MAX=3
 export HARNESS_ECOSYSTEM="auto"
 # Optional install override (eval in work dir after env file is created)
 # export HARNESS_INSTALL_CMD="make deps"
+# Node package manager: auto-detected from package.json "packageManager" and the
+# lockfile (bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm),
+# falling back to whichever is installed. Set to pin one: npm | bun | pnpm | yarn
+# export HARNESS_NODE_PACKAGE_MANAGER="bun"
 
 # Shared infrastructure — space-separated docker compose service names from
 # docker-compose.agent.yml, started ONCE by setup-infra.sh and shared by all
@@ -38,6 +42,119 @@ har_infra_enabled() {
   esac
 }
 
+# ── Node package manager helpers ──────────────────────────────────────────────
+# Mirrored verbatim in harness.env and provision-toolchain.sh so a sourcing
+# script and the provisioning subprocess resolve the same tool.
+
+# Package managers HAR can drive, in fallback preference order.
+HAR_NODE_PACKAGE_MANAGERS="npm bun pnpm yarn"
+
+# Package manager the repo declares: an explicit HARNESS_NODE_PACKAGE_MANAGER
+# wins, then package.json "packageManager", then the lockfile. Empty when the
+# repo says nothing.
+har_node_declared_package_manager() {
+  local dir="${1:-.}"
+
+  if [ -n "${HARNESS_NODE_PACKAGE_MANAGER:-}" ]; then
+    echo "$HARNESS_NODE_PACKAGE_MANAGER"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then
+    local field
+    field="$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([a-z]*\)@.*/\1/p' "$dir/package.json" | head -1)"
+    if [ -n "$field" ]; then
+      echo "$field"
+      return
+    fi
+  fi
+  if [ -f "$dir/bun.lock" ] || [ -f "$dir/bun.lockb" ]; then echo bun; return; fi
+  if [ -f "$dir/pnpm-lock.yaml" ]; then echo pnpm; return; fi
+  if [ -f "$dir/yarn.lock" ]; then echo yarn; return; fi
+  if [ -f "$dir/package-lock.json" ]; then echo npm; return; fi
+  echo ""
+}
+
+# Package manager to actually run. A manager the repo declares but this machine
+# lacks falls back to one that is installed, so a repo pinned to npm still
+# provisions on a bun-only machine (and the reverse).
+har_node_package_manager() {
+  local dir="${1:-.}"
+  local declared
+  declared="$(har_node_declared_package_manager "$dir")"
+
+  if [ -n "$declared" ] && command -v "$declared" >/dev/null 2>&1; then
+    echo "$declared"
+    return
+  fi
+
+  local candidate
+  for candidate in $HAR_NODE_PACKAGE_MANAGERS; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return
+    fi
+  done
+
+  echo "${declared:-npm}"
+}
+
+# Lockfile a manager writes, so a substitute install can clean up after itself.
+har_node_lockfile() {
+  case "$1" in
+    bun) echo "bun.lock" ;;
+    npm) echo "package-lock.json" ;;
+    pnpm) echo "pnpm-lock.yaml" ;;
+    yarn) echo "yarn.lock" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Install dependencies in a directory. When a substitute manager stands in for
+# the one the repo declares, any lockfile it creates is removed afterwards:
+# provisioning must not migrate the repo to a different package manager.
+# (bun writes bun.lock even under --no-save, so the flags alone are not enough.)
+har_node_install() {
+  local dir="$1"
+  local manager="$2"
+  local declared="${3:-}"
+  local substituting=false
+  local lockfile=""
+  local had_lockfile=false
+
+  if [ -n "$declared" ] && [ "$declared" != "$manager" ]; then
+    substituting=true
+    lockfile="$(har_node_lockfile "$manager")"
+    if [ -n "$lockfile" ] && [ -e "$dir/$lockfile" ]; then
+      had_lockfile=true
+    fi
+  fi
+
+  local code=0
+  (cd "$dir" && "$manager" install --silent) || code=$?
+
+  if [ "$substituting" = true ] && [ "$had_lockfile" = false ] && [ -n "$lockfile" ]; then
+    rm -f "$dir/$lockfile"
+    [ "$manager" = "bun" ] && rm -f "$dir/bun.lockb"
+  fi
+  return $code
+}
+
+# Package runner (npx equivalent) for one-off CLIs such as pm2, including the
+# flag that keeps it non-interactive. Takes a manager name, or none to resolve
+# from the environment and PATH.
+har_pkg_exec() {
+  case "${1:-${HARNESS_NODE_PACKAGE_MANAGER:-}}" in
+    bun) echo "bunx"; return ;;
+    pnpm) echo "pnpm dlx"; return ;;
+    yarn) echo "yarn dlx"; return ;;
+    npm) echo "npx --yes"; return ;;
+  esac
+  if command -v npx >/dev/null 2>&1; then echo "npx --yes"; return; fi
+  if command -v bunx >/dev/null 2>&1; then echo "bunx"; return; fi
+  if command -v pnpm >/dev/null 2>&1; then echo "pnpm dlx"; return; fi
+  echo "npx --yes"
+}
+
 # Postgres client — uses host tools when installed, otherwise docker exec into
 # the shared db container. Usage: har_pg psql -d postgres -c "SELECT 1"
 har_pg() {

package/dist/templates/har-boilerplate-cli/launch.sh

@@ -187,8 +187,9 @@ elif [ -f "$SCRIPT_DIR/provision-toolchain.sh" ]; then
   HAR_AGENT_ID="$AGENT_ID" \
     "$SCRIPT_DIR/provision-toolchain.sh"
 elif [ -f "$WORK_DIR/package.json" ] && [ ! -d "$WORK_DIR/node_modules" ]; then
-  log "Installing dependencies in $WORK_DIR..."
-  (cd "$WORK_DIR" && npm install --silent)
+  PKG_MANAGER="$(har_node_package_manager "$WORK_DIR")"
+  log "Installing dependencies in $WORK_DIR with ${PKG_MANAGER}..."
+  har_node_install "$WORK_DIR" "$PKG_MANAGER" "$(har_node_declared_package_manager "$WORK_DIR")"
 fi
 
 SLOT_AGENT_ID="$AGENT_ID" \

package/dist/templates/har-boilerplate-cli/provision-toolchain.sh

@@ -27,6 +27,119 @@ pt_log() {
   fi
 }
 
+# ── Node package manager helpers ──────────────────────────────────────────────
+# Mirrored verbatim in harness.env and provision-toolchain.sh so a sourcing
+# script and the provisioning subprocess resolve the same tool.
+
+# Package managers HAR can drive, in fallback preference order.
+HAR_NODE_PACKAGE_MANAGERS="npm bun pnpm yarn"
+
+# Package manager the repo declares: an explicit HARNESS_NODE_PACKAGE_MANAGER
+# wins, then package.json "packageManager", then the lockfile. Empty when the
+# repo says nothing.
+har_node_declared_package_manager() {
+  local dir="${1:-.}"
+
+  if [ -n "${HARNESS_NODE_PACKAGE_MANAGER:-}" ]; then
+    echo "$HARNESS_NODE_PACKAGE_MANAGER"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then
+    local field
+    field="$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([a-z]*\)@.*/\1/p' "$dir/package.json" | head -1)"
+    if [ -n "$field" ]; then
+      echo "$field"
+      return
+    fi
+  fi
+  if [ -f "$dir/bun.lock" ] || [ -f "$dir/bun.lockb" ]; then echo bun; return; fi
+  if [ -f "$dir/pnpm-lock.yaml" ]; then echo pnpm; return; fi
+  if [ -f "$dir/yarn.lock" ]; then echo yarn; return; fi
+  if [ -f "$dir/package-lock.json" ]; then echo npm; return; fi
+  echo ""
+}
+
+# Package manager to actually run. A manager the repo declares but this machine
+# lacks falls back to one that is installed, so a repo pinned to npm still
+# provisions on a bun-only machine (and the reverse).
+har_node_package_manager() {
+  local dir="${1:-.}"
+  local declared
+  declared="$(har_node_declared_package_manager "$dir")"
+
+  if [ -n "$declared" ] && command -v "$declared" >/dev/null 2>&1; then
+    echo "$declared"
+    return
+  fi
+
+  local candidate
+  for candidate in $HAR_NODE_PACKAGE_MANAGERS; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return
+    fi
+  done
+
+  echo "${declared:-npm}"
+}
+
+# Lockfile a manager writes, so a substitute install can clean up after itself.
+har_node_lockfile() {
+  case "$1" in
+    bun) echo "bun.lock" ;;
+    npm) echo "package-lock.json" ;;
+    pnpm) echo "pnpm-lock.yaml" ;;
+    yarn) echo "yarn.lock" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Install dependencies in a directory. When a substitute manager stands in for
+# the one the repo declares, any lockfile it creates is removed afterwards:
+# provisioning must not migrate the repo to a different package manager.
+# (bun writes bun.lock even under --no-save, so the flags alone are not enough.)
+har_node_install() {
+  local dir="$1"
+  local manager="$2"
+  local declared="${3:-}"
+  local substituting=false
+  local lockfile=""
+  local had_lockfile=false
+
+  if [ -n "$declared" ] && [ "$declared" != "$manager" ]; then
+    substituting=true
+    lockfile="$(har_node_lockfile "$manager")"
+    if [ -n "$lockfile" ] && [ -e "$dir/$lockfile" ]; then
+      had_lockfile=true
+    fi
+  fi
+
+  local code=0
+  (cd "$dir" && "$manager" install --silent) || code=$?
+
+  if [ "$substituting" = true ] && [ "$had_lockfile" = false ] && [ -n "$lockfile" ]; then
+    rm -f "$dir/$lockfile"
+    [ "$manager" = "bun" ] && rm -f "$dir/bun.lockb"
+  fi
+  return $code
+}
+
+# Package runner (npx equivalent) for one-off CLIs such as pm2, including the
+# flag that keeps it non-interactive. Takes a manager name, or none to resolve
+# from the environment and PATH.
+har_pkg_exec() {
+  case "${1:-${HARNESS_NODE_PACKAGE_MANAGER:-}}" in
+    bun) echo "bunx"; return ;;
+    pnpm) echo "pnpm dlx"; return ;;
+    yarn) echo "yarn dlx"; return ;;
+    npm) echo "npx --yes"; return ;;
+  esac
+  if command -v npx >/dev/null 2>&1; then echo "npx --yes"; return; fi
+  if command -v bunx >/dev/null 2>&1; then echo "bunx"; return; fi
+  if command -v pnpm >/dev/null 2>&1; then echo "pnpm dlx"; return; fi
+  echo "npx --yes"
+}
+
 append_env() {
   local key="$1"
   local value="$2"
@@ -81,32 +194,37 @@ run_install_cmd() {
 
 provision_node() {
   local dir="$1"
-  local npm_bin="npm"
   local node_bin="node"
+  local pkg_manager declared_manager
+  declared_manager="$(har_node_declared_package_manager "$dir")"
+  pkg_manager="$(har_node_package_manager "$dir")"
+
+  if [ -n "$declared_manager" ] && [ "$declared_manager" != "$pkg_manager" ]; then
+    pt_log "Repo declares ${declared_manager}, which is not on PATH — installing with ${pkg_manager} and leaving the lockfile untouched."
+  fi
 
   if ! run_install_cmd "$dir"; then
-    pt_log "Installing Node dependencies..."
-    if [ -f "$dir/pnpm-lock.yaml" ] && command -v pnpm >/dev/null 2>&1; then
-      (cd "$dir" && pnpm install --silent)
-      npm_bin="pnpm"
-    elif [ -f "$dir/yarn.lock" ] && command -v yarn >/dev/null 2>&1; then
-      (cd "$dir" && yarn install --silent)
-      npm_bin="yarn"
-    else
-      (cd "$dir" && npm install --silent)
-    fi
+    pt_log "Installing Node dependencies with ${pkg_manager}..."
+    har_node_install "$dir" "$pkg_manager" "$declared_manager"
   fi
 
   if command -v node >/dev/null 2>&1; then
     node_bin="$(command -v node)"
+  elif [ "$pkg_manager" = "bun" ]; then
+    # bun-only machine: bun runs the `node -e` snippets verify.sh relies on.
+    node_bin="$(command -v bun)"
   fi
-  if [ "$npm_bin" = "npm" ] && command -v npm >/dev/null 2>&1; then
-    npm_bin="$(command -v npm)"
+
+  local npm_bin="$pkg_manager"
+  if command -v "$pkg_manager" >/dev/null 2>&1; then
+    npm_bin="$(command -v "$pkg_manager")"
   fi
 
   append_env "HARNESS_ECOSYSTEM" "node"
   append_env "NODE_BIN" "$node_bin"
   append_env "NPM_BIN" "$npm_bin"
+  append_env "HARNESS_NODE_PACKAGE_MANAGER" "$pkg_manager"
+  append_env "HARNESS_PKG_EXEC" "$(har_pkg_exec "$pkg_manager")"
   append_path_prefix "$dir/node_modules/.bin"
 }
 
@@ -252,8 +370,11 @@ provision_monorepo_root() {
   [ -n "$HAR_WORKTREE_DIR" ] || return 0
   [ -f "$HAR_WORKTREE_DIR/package.json" ] || return 0
   [ -d "$HAR_WORKTREE_DIR/node_modules" ] && return 0
-  pt_log "Installing monorepo root dependencies in $HAR_WORKTREE_DIR..."
-  (cd "$HAR_WORKTREE_DIR" && npm install --silent)
+  local pkg_manager
+  pkg_manager="$(har_node_package_manager "$HAR_WORKTREE_DIR")"
+  pt_log "Installing monorepo root dependencies in $HAR_WORKTREE_DIR with ${pkg_manager}..."
+  har_node_install "$HAR_WORKTREE_DIR" "$pkg_manager" \
+    "$(har_node_declared_package_manager "$HAR_WORKTREE_DIR")"
 }
 
 provision_ecosystem() {

package/dist/templates/har-boilerplate-cli/setup-infra.sh

@@ -165,7 +165,7 @@ fi
 SHARED_ECOSYSTEM="$SCRIPT_DIR/ecosystem.shared.config.cjs"
 if [ -f "$SHARED_ECOSYSTEM" ]; then
   log "Starting shared app services from ecosystem.shared.config.cjs..."
-  (cd "$REPO_ROOT" && npx --yes pm2 startOrReload "$SHARED_ECOSYSTEM" >/dev/null)
+  (cd "$REPO_ROOT" && $(har_pkg_exec) pm2 startOrReload "$SHARED_ECOSYSTEM" >/dev/null)
   log "Shared app services running (pm2 ls | grep har-${HARNESS_PROJECT_NAME}-shared-)."
 fi
 

package/dist/templates/har-boilerplate-ios/harness.env

@@ -10,6 +10,10 @@ export HARNESS_AGENT_SLOT_MAX=3
 # Toolchain provisioning — launch writes Xcode/simulator paths into .env.agent.<id>
 export HARNESS_ECOSYSTEM="ios"
 # export HARNESS_INSTALL_CMD="xcodebuild -resolvePackageDependencies ..."
+# Node package manager: auto-detected from package.json "packageManager" and the
+# lockfile (bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm),
+# falling back to whichever is installed. Set to pin one: npm | bun | pnpm | yarn
+# export HARNESS_NODE_PACKAGE_MANAGER="bun"
 
 # ── Xcode project ─────────────────────────────────────────────────────────────
 # Set one of HARNESS_XCODE_WORKSPACE or HARNESS_XCODE_PROJECT (workspace wins).
@@ -70,6 +74,119 @@ har_infra_enabled() {
   esac
 }
 
+# ── Node package manager helpers ──────────────────────────────────────────────
+# Mirrored verbatim in harness.env and provision-toolchain.sh so a sourcing
+# script and the provisioning subprocess resolve the same tool.
+
+# Package managers HAR can drive, in fallback preference order.
+HAR_NODE_PACKAGE_MANAGERS="npm bun pnpm yarn"
+
+# Package manager the repo declares: an explicit HARNESS_NODE_PACKAGE_MANAGER
+# wins, then package.json "packageManager", then the lockfile. Empty when the
+# repo says nothing.
+har_node_declared_package_manager() {
+  local dir="${1:-.}"
+
+  if [ -n "${HARNESS_NODE_PACKAGE_MANAGER:-}" ]; then
+    echo "$HARNESS_NODE_PACKAGE_MANAGER"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then
+    local field
+    field="$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([a-z]*\)@.*/\1/p' "$dir/package.json" | head -1)"
+    if [ -n "$field" ]; then
+      echo "$field"
+      return
+    fi
+  fi
+  if [ -f "$dir/bun.lock" ] || [ -f "$dir/bun.lockb" ]; then echo bun; return; fi
+  if [ -f "$dir/pnpm-lock.yaml" ]; then echo pnpm; return; fi
+  if [ -f "$dir/yarn.lock" ]; then echo yarn; return; fi
+  if [ -f "$dir/package-lock.json" ]; then echo npm; return; fi
+  echo ""
+}
+
+# Package manager to actually run. A manager the repo declares but this machine
+# lacks falls back to one that is installed, so a repo pinned to npm still
+# provisions on a bun-only machine (and the reverse).
+har_node_package_manager() {
+  local dir="${1:-.}"
+  local declared
+  declared="$(har_node_declared_package_manager "$dir")"
+
+  if [ -n "$declared" ] && command -v "$declared" >/dev/null 2>&1; then
+    echo "$declared"
+    return
+  fi
+
+  local candidate
+  for candidate in $HAR_NODE_PACKAGE_MANAGERS; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return
+    fi
+  done
+
+  echo "${declared:-npm}"
+}
+
+# Lockfile a manager writes, so a substitute install can clean up after itself.
+har_node_lockfile() {
+  case "$1" in
+    bun) echo "bun.lock" ;;
+    npm) echo "package-lock.json" ;;
+    pnpm) echo "pnpm-lock.yaml" ;;
+    yarn) echo "yarn.lock" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Install dependencies in a directory. When a substitute manager stands in for
+# the one the repo declares, any lockfile it creates is removed afterwards:
+# provisioning must not migrate the repo to a different package manager.
+# (bun writes bun.lock even under --no-save, so the flags alone are not enough.)
+har_node_install() {
+  local dir="$1"
+  local manager="$2"
+  local declared="${3:-}"
+  local substituting=false
+  local lockfile=""
+  local had_lockfile=false
+
+  if [ -n "$declared" ] && [ "$declared" != "$manager" ]; then
+    substituting=true
+    lockfile="$(har_node_lockfile "$manager")"
+    if [ -n "$lockfile" ] && [ -e "$dir/$lockfile" ]; then
+      had_lockfile=true
+    fi
+  fi
+
+  local code=0
+  (cd "$dir" && "$manager" install --silent) || code=$?
+
+  if [ "$substituting" = true ] && [ "$had_lockfile" = false ] && [ -n "$lockfile" ]; then
+    rm -f "$dir/$lockfile"
+    [ "$manager" = "bun" ] && rm -f "$dir/bun.lockb"
+  fi
+  return $code
+}
+
+# Package runner (npx equivalent) for one-off CLIs such as pm2, including the
+# flag that keeps it non-interactive. Takes a manager name, or none to resolve
+# from the environment and PATH.
+har_pkg_exec() {
+  case "${1:-${HARNESS_NODE_PACKAGE_MANAGER:-}}" in
+    bun) echo "bunx"; return ;;
+    pnpm) echo "pnpm dlx"; return ;;
+    yarn) echo "yarn dlx"; return ;;
+    npm) echo "npx --yes"; return ;;
+  esac
+  if command -v npx >/dev/null 2>&1; then echo "npx --yes"; return; fi
+  if command -v bunx >/dev/null 2>&1; then echo "bunx"; return; fi
+  if command -v pnpm >/dev/null 2>&1; then echo "pnpm dlx"; return; fi
+  echo "npx --yes"
+}
+
 # Optional "agent usable" smoke beyond build/test, such as a simulator flow or
 # backend-auth check. Enable only when this project needs it.
 # export HARNESS_READINESS_CMD="./.har/readiness.sh"