@osfactory/har 0.64.2 → 1.0.0-rc.1

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

@@ -1,5 +1,9 @@
 # Shared harness configuration — edit to match your project
 # Generated by har env init, maintained over time with har env maintain
+#
+# This file is pure KEY=value config (plus comments) and is schema-validated
+# on read. Runtime helpers (har_infra_enabled, har_pg, port resolution) live
+# in .har/lib/ — never define functions here.
 
 export HARNESS_PROJECT_NAME=__PROJECT_NAME__
 export HARNESS_USE_WORKTREE=true
@@ -21,26 +25,10 @@ export HARNESS_PORT_STEP=10
 export HARNESS_HEALTH_CHECK_PATH=/health
 
 # ── Shared infra host ports (one per machine) ─────────────────────────────────
-# setup-infra.sh tries DEFAULT first, then scans SCAN_START..SCAN_END when busy.
+# One lane per infra service: <lane>=<default>:<scan_start>-<scan_end>.
+# setup-infra.sh tries the default first, then scans the range when busy.
 # Persisted in .har/state/infra.env — do not hardcode these ports in app code.
-export HARNESS_DB_PORT_DEFAULT=15432
-export HARNESS_DB_PORT_SCAN_START=15432
-export HARNESS_DB_PORT_SCAN_END=15499
-export HARNESS_MINIO_PORT_DEFAULT=19000
-export HARNESS_MINIO_PORT_SCAN_START=19000
-export HARNESS_MINIO_PORT_SCAN_END=19099
-export HARNESS_MINIO_CONSOLE_PORT_DEFAULT=19001
-export HARNESS_MINIO_CONSOLE_PORT_SCAN_START=19001
-export HARNESS_MINIO_CONSOLE_PORT_SCAN_END=19099
-export HARNESS_BROWSER_PORT_DEFAULT=13001
-export HARNESS_BROWSER_PORT_SCAN_START=13001
-export HARNESS_BROWSER_PORT_SCAN_END=13099
-export HARNESS_MAILPIT_WEB_PORT_DEFAULT=18025
-export HARNESS_MAILPIT_WEB_PORT_SCAN_START=18025
-export HARNESS_MAILPIT_WEB_PORT_SCAN_END=18099
-export HARNESS_MAILPIT_SMTP_PORT_DEFAULT=11025
-export HARNESS_MAILPIT_SMTP_PORT_SCAN_START=11025
-export HARNESS_MAILPIT_SMTP_PORT_SCAN_END=11099
+export HARNESS_INFRA_PORT_LANES="db=15432:15432-15499 minio=19000:19000-19049 minio-console=19050:19050-19099 browser=13001:13001-13099 mailpit-web=18025:18025-18099 mailpit-smtp=11025:11025-11099"
 
 # Agent slot limits — canonical source: .har/stages.json (agentSlots).
 # Legacy fallback below; har env maintain --finalize syncs these from stages.json.
@@ -62,142 +50,10 @@ export HARNESS_ECOSYSTEM="auto"
 # list the ones this project needs here (e.g. "db redis mailpit").
 export HARNESS_INFRA_SERVICES="db"
 
-# Returns 0 when a shared infra service is enabled: har_infra_enabled db
-har_infra_enabled() {
-  case " ${HARNESS_INFRA_SERVICES:-} " in
-    *" $1 "*) return 0 ;;
-    *) return 1 ;;
-  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 createdb -T template_x agent_1
-har_pg() {
-  local tool="$1"; shift
-  if command -v "$tool" >/dev/null 2>&1; then
-    PGPASSWORD=password "$tool" -h localhost -p "${AGENT_DB_PORT:-15432}" -U postgres "$@"
-  else
-    docker exec -i -e PGPASSWORD=password "har-${HARNESS_PROJECT_NAME}-db-1" "$tool" -U postgres "$@"
-  fi
-}
-
-# Database setup commands (run once against template DB in setup-infra.sh)
-export HARNESS_DB_MIGRATE_CMD="echo 'TODO: set migrate command'"
-export HARNESS_DB_SEED_CMD="echo 'TODO: set seed command'"
+# Database setup commands (run once against template DB in setup-infra.sh).
+# Empty = not configured; setup-infra.sh skips the step.
+export HARNESS_DB_MIGRATE_CMD=""
+export HARNESS_DB_SEED_CMD=""
 
 # Optional readiness/data hooks for larger apps. Enable only when this project
 # needs them, and keep the scripts idempotent.

package/dist/templates/har-boilerplate/stages.json

@@ -32,9 +32,11 @@
     {
       "id": "verify",
       "kind": "verify",
-      "description": "Verification pipeline (quick smoke by default; --full runs the registry's verificationStages)",
+      "description": "Verification pipeline: runs stages.json verificationStages in order (tier \"quick\" by default; --full runs the whole list)",
       "command": "./.har/verify.sh {agentId}",
-      "acceptsArgs": ["--full"],
+      "acceptsArgs": [
+        "--full"
+      ],
       "artifacts": [
         {
           "path": ".har/artifacts",
@@ -67,6 +69,53 @@
       "kind": "teardown",
       "description": "Stop processes and release agent slot resources",
       "command": "./.har/teardown.sh {agentId}"
+    },
+    {
+      "id": "typecheck",
+      "kind": "test",
+      "tier": "quick",
+      "description": "Ecosystem quick smoke (registered from HARNESS_ECOSYSTEM at init; adapt to this repo)",
+      "command": "${NPM_BIN:-npm} run typecheck",
+      "requiresAgentId": true
+    },
+    {
+      "id": "api-health",
+      "kind": "test",
+      "tier": "quick",
+      "description": "API health endpoint for the slot's primary app",
+      "script": "stages/api-health.sh",
+      "requiresAgentId": true
+    },
+    {
+      "id": "unit-tests",
+      "kind": "test",
+      "tier": "full",
+      "description": "Unit tests",
+      "command": "${NPM_BIN:-npm} test",
+      "requiresAgentId": true
+    },
+    {
+      "id": "lint",
+      "kind": "test",
+      "tier": "full",
+      "description": "Lint",
+      "command": "${NPM_BIN:-npm} run lint",
+      "requiresAgentId": true
+    },
+    {
+      "id": "readiness",
+      "kind": "test",
+      "tier": "full",
+      "description": "Project readiness smoke (HARNESS_READINESS_CMD)",
+      "script": "stages/readiness.sh",
+      "requiresAgentId": true
     }
+  ],
+  "verificationStages": [
+    "typecheck",
+    "api-health",
+    "unit-tests",
+    "lint",
+    "readiness"
   ]
 }

package/dist/templates/har-boilerplate-cli/docker-compose.agent.yml

@@ -32,7 +32,7 @@ services:
     image: coollabsio/minio:latest
     ports:
       - "${AGENT_MINIO_PORT:-19000}:9000"
-      - "${AGENT_MINIO_CONSOLE_PORT:-19001}:9001"
+      - "${AGENT_MINIO_CONSOLE_PORT:-19050}:9001"
     volumes:
       - agent-minio-data:/minio/data
     environment:

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

@@ -1,5 +1,9 @@
 # CLI / library harness — optional Docker via HARNESS_INFRA_SERVICES, no PM2
 # Generated by har env init --profile cli
+#
+# This file is pure KEY=value config (plus comments) and is schema-validated
+# on read. Runtime helpers (har_infra_enabled, har_pg, port resolution) live
+# in .har/lib/ — never define functions here.
 
 export HARNESS_PROJECT_NAME=__PROJECT_NAME__
 export HARNESS_USE_WORKTREE=true
@@ -10,10 +14,10 @@ export HARNESS_API_BASE_PORT=8000
 export HARNESS_PORT_STEP=10
 export HARNESS_HEALTH_CHECK_PATH=
 
-# Shared infra host ports — setup-infra.sh tries DEFAULT first, scans when busy.
-export HARNESS_DB_PORT_DEFAULT=15432
-export HARNESS_DB_PORT_SCAN_START=15432
-export HARNESS_DB_PORT_SCAN_END=15499
+# Shared infra host ports — one lane per infra service:
+# <lane>=<default>:<scan_start>-<scan_end>. setup-infra.sh tries the default
+# first, scans the range when busy.
+export HARNESS_INFRA_PORT_LANES="db=15432:15432-15499"
 
 export HARNESS_AGENT_SLOT_MIN=1
 export HARNESS_AGENT_SLOT_MAX=3
@@ -34,140 +38,10 @@ export HARNESS_ECOSYSTEM="auto"
 # compose file, then list the ones this project needs here (e.g. "db redis").
 export HARNESS_INFRA_SERVICES=""
 
-# Returns 0 when a shared infra service is enabled: har_infra_enabled db
-har_infra_enabled() {
-  case " ${HARNESS_INFRA_SERVICES:-} " in
-    *" $1 "*) return 0 ;;
-    *) return 1 ;;
-  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() {
-  local tool="$1"; shift
-  if command -v "$tool" >/dev/null 2>&1; then
-    PGPASSWORD=password "$tool" -h localhost -p "${AGENT_DB_PORT:-15432}" -U postgres "$@"
-  else
-    docker exec -i -e PGPASSWORD=password "har-${HARNESS_PROJECT_NAME}-db-1" "$tool" -U postgres "$@"
-  fi
-}
-
-export HARNESS_DB_MIGRATE_CMD="true"
-export HARNESS_DB_SEED_CMD="true"
+# Database setup commands (run once against template DB in setup-infra.sh).
+# Empty = not configured; setup-infra.sh skips the step.
+export HARNESS_DB_MIGRATE_CMD=""
+export HARNESS_DB_SEED_CMD=""
 
 # Optional readiness/data hooks for repositories that need more than static
 # CLI/library checks. Enable only when this project needs them, and keep scripts

package/dist/templates/har-boilerplate-cli/stages.json

@@ -32,9 +32,11 @@
     {
       "id": "verify",
       "kind": "verify",
-      "description": "Verification pipeline (quick smoke by default; --full runs the registry's verificationStages)",
+      "description": "Verification pipeline: runs stages.json verificationStages in order (tier \"quick\" by default; --full runs the whole list)",
       "command": "./.har/verify.sh {agentId}",
-      "acceptsArgs": ["--full"],
+      "acceptsArgs": [
+        "--full"
+      ],
       "artifacts": [
         {
           "path": ".har/artifacts",
@@ -61,6 +63,44 @@
       "kind": "teardown",
       "description": "Remove worktree and env file for the slot",
       "command": "./.har/teardown.sh {agentId}"
+    },
+    {
+      "id": "typecheck",
+      "kind": "test",
+      "tier": "quick",
+      "description": "Ecosystem quick smoke (registered from HARNESS_ECOSYSTEM at init; adapt to this repo)",
+      "command": "${NPM_BIN:-npm} run typecheck",
+      "requiresAgentId": true
+    },
+    {
+      "id": "unit-tests",
+      "kind": "test",
+      "tier": "full",
+      "description": "Unit tests",
+      "command": "${NPM_BIN:-npm} test",
+      "requiresAgentId": true
+    },
+    {
+      "id": "lint",
+      "kind": "test",
+      "tier": "full",
+      "description": "Lint",
+      "command": "${NPM_BIN:-npm} run lint",
+      "requiresAgentId": true
+    },
+    {
+      "id": "readiness",
+      "kind": "test",
+      "tier": "full",
+      "description": "Project readiness smoke (HARNESS_READINESS_CMD)",
+      "script": "stages/readiness.sh",
+      "requiresAgentId": true
     }
+  ],
+  "verificationStages": [
+    "typecheck",
+    "unit-tests",
+    "lint",
+    "readiness"
   ]
 }

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

@@ -1,5 +1,9 @@
 # iOS mobile app harness — Xcode / iOS Simulator, no PM2, no Docker infra
 # Generated by har env init --profile ios
+#
+# This file is pure KEY=value config (plus comments) and is schema-validated
+# on read. Runtime helpers (har_infra_enabled, port resolution) live in
+# .har/lib/ — never define functions here.
 
 export HARNESS_PROJECT_NAME=__PROJECT_NAME__
 export HARNESS_USE_WORKTREE=true
@@ -60,139 +64,19 @@ export HARNESS_SIMULATOR_FAMILY="auto"
 export HARNESS_SIMULATOR_SHARED=false
 
 # Destination used when slots share a simulator; per-slot launches override it
-# with the reserved device's UDID.
-export HARNESS_IOS_DESTINATION="platform=iOS Simulator,name=${HARNESS_SIMULATOR_NAME}"
+# with the reserved device's UDID. Empty = derived from HARNESS_SIMULATOR_NAME.
+export HARNESS_IOS_DESTINATION=""
 
-# Optional SwiftLint path (leave empty to use system-installed swiftlint).
-export HARNESS_SWIFTLINT_CMD="${HARNESS_SWIFTLINT_CMD:-swiftlint}"
+# Optional SwiftLint path (empty = system-installed swiftlint).
+# export HARNESS_SWIFTLINT_CMD="swiftlint"
 
 # ── Infrastructure ────────────────────────────────────────────────────────────
 # No Docker infra for pure iOS apps. Set service names here (space-separated)
 # only if your app needs a local backend container (e.g. a mock server).
-# When enabled, add matching HARNESS_*_PORT_DEFAULT / SCAN_* vars for each service.
+# When enabled, declare a matching port lane for each service:
+# export HARNESS_INFRA_PORT_LANES="mock-server=18080:18080-18099"
 export HARNESS_INFRA_SERVICES=""
 
-# Returns 0 when a shared infra service is enabled: har_infra_enabled mock-server
-har_infra_enabled() {
-  case " ${HARNESS_INFRA_SERVICES:-} " in
-    *" $1 "*) return 0 ;;
-    *) return 1 ;;
-  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"