@osfactory/har 0.5.0 → 0.7.0

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

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Launch readiness gate for CLI/library harnesses (occupied slot only).
+# Usage: ./.har/preflight.sh <agent-id> [--replace] [--force]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:-}"
+FORCE=false
+REPLACE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --replace) REPLACE=true ;;
+    --force)   FORCE=true ;;
+  esac
+done
+
+if [[ -z "$AGENT_ID" ]]; then
+  echo "Usage: $0 <agent-id> [--replace] [--force]" >&2
+  exit 1
+fi
+
+validate_agent_id "$AGENT_ID"
+
+if har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE"; then
+  echo "Slot ${AGENT_ID}: ready to launch."
+  exit 0
+fi
+
+exit $?

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

@@ -0,0 +1,285 @@
+#!/usr/bin/env bash
+# Provision the project toolchain and append resolved paths to .env.agent.<id>.
+# Called from launch.sh after the agent env file is created.
+#
+# Configure in harness.env:
+#   HARNESS_ECOSYSTEM   — auto (default) | node | python | go | rust | java | ruby | ios | none
+#   HARNESS_INSTALL_CMD — optional override (eval in HAR_WORK_DIR)
+# Ecosystem-specific optional overrides:
+#   HARNESS_PYTHON_VENV_DIR — Python venv path relative to HAR_WORK_DIR (default: .har/venv)
+#
+# Required env from caller: HAR_WORK_DIR, HAR_ENV_FILE
+# Optional: HAR_WORKTREE_DIR, HAR_REL_PREFIX, HAR_AGENT_ID (for logging)
+set -euo pipefail
+
+: "${HAR_WORK_DIR:?HAR_WORK_DIR is required}"
+: "${HAR_ENV_FILE:?HAR_ENV_FILE is required}"
+
+HAR_WORKTREE_DIR="${HAR_WORKTREE_DIR:-}"
+HAR_REL_PREFIX="${HAR_REL_PREFIX:-}"
+HAR_AGENT_ID="${HAR_AGENT_ID:-}"
+
+pt_log() {
+  if [ -n "$HAR_AGENT_ID" ]; then
+    echo "==> [agent-${HAR_AGENT_ID}] toolchain: $*" >&2
+  else
+    echo "==> [provision-toolchain] $*" >&2
+  fi
+}
+
+append_env() {
+  local key="$1"
+  local value="$2"
+  printf '%s=%s\n' "$key" "$value" >> "$HAR_ENV_FILE"
+}
+
+append_path_prefix() {
+  local prefix="$1"
+  [ -n "$prefix" ] && [ -d "$prefix" ] || return 0
+  append_env "PATH" "${prefix}:${PATH:-$PATH}"
+}
+
+detect_ecosystem() {
+  local dir="$1"
+  local configured="${HARNESS_ECOSYSTEM:-auto}"
+  if [ -n "$configured" ] && [ "$configured" != "auto" ]; then
+    echo "$configured"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then echo node; return; fi
+  if [ -f "$dir/pyproject.toml" ] || [ -f "$dir/setup.py" ] || [ -f "$dir/setup.cfg" ] \
+    || [ -f "$dir/requirements.txt" ] || [ -f "$dir/Pipfile" ]; then
+    echo python
+    return
+  fi
+  if [ -f "$dir/go.mod" ]; then echo go; return; fi
+  if [ -f "$dir/Cargo.toml" ]; then echo rust; return; fi
+  if [ -f "$dir/pom.xml" ] || [ -f "$dir/build.gradle" ] || [ -f "$dir/build.gradle.kts" ]; then
+    echo java
+    return
+  fi
+  if [ -f "$dir/Gemfile" ]; then echo ruby; return; fi
+  if [ -n "${HARNESS_XCODE_SCHEME:-}" ] || [ -n "${HARNESS_XCODE_PROJECT:-}" ] \
+    || [ -n "${HARNESS_XCODE_WORKSPACE:-}" ]; then
+    echo ios
+    return
+  fi
+  echo none
+}
+
+run_install_cmd() {
+  local dir="$1"
+  if [ -n "${HARNESS_INSTALL_CMD:-}" ]; then
+    pt_log "Running HARNESS_INSTALL_CMD..."
+    (cd "$dir" && eval "$HARNESS_INSTALL_CMD")
+    return
+  fi
+  return 1
+}
+
+provision_node() {
+  local dir="$1"
+  local npm_bin="npm"
+  local node_bin="node"
+
+  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
+  fi
+
+  if command -v node >/dev/null 2>&1; then
+    node_bin="$(command -v node)"
+  fi
+  if [ "$npm_bin" = "npm" ] && command -v npm >/dev/null 2>&1; then
+    npm_bin="$(command -v npm)"
+  fi
+
+  append_env "HARNESS_ECOSYSTEM" "node"
+  append_env "NODE_BIN" "$node_bin"
+  append_env "NPM_BIN" "$npm_bin"
+  append_path_prefix "$dir/node_modules/.bin"
+}
+
+provision_python() {
+  local dir="$1"
+  local venv_rel="${HARNESS_PYTHON_VENV_DIR:-.har/venv}"
+  local venv_dir="$dir/$venv_rel"
+  local python_bin="python3"
+
+  if ! command -v python3 >/dev/null 2>&1; then
+    pt_log "python3 not found on PATH — skipping venv provisioning"
+    append_env "HARNESS_ECOSYSTEM" "python"
+    append_env "PYTHON_BIN" "${PYTHON_BIN:-python3}"
+    return
+  fi
+
+  if [ ! -d "$venv_dir" ]; then
+    pt_log "Creating Python venv at $venv_rel..."
+    if ! python3 -m venv "$venv_dir"; then
+      rm -rf "$venv_dir"
+      pt_log "python3 -m venv failed (on Debian/Ubuntu install python3-venv) — using system python3"
+      append_env "HARNESS_ECOSYSTEM" "python"
+      append_env "PYTHON_BIN" "$(command -v python3)"
+      return
+    fi
+  fi
+
+  if [ ! -x "$venv_dir/bin/python" ]; then
+    pt_log "Python venv at $venv_rel is missing or broken — using system python3"
+    append_env "HARNESS_ECOSYSTEM" "python"
+    append_env "PYTHON_BIN" "$(command -v python3)"
+    return
+  fi
+
+  python_bin="$venv_dir/bin/python"
+  # shellcheck disable=SC1091
+  source "$venv_dir/bin/activate"
+
+  if ! run_install_cmd "$dir"; then
+    pt_log "Installing Python dependencies..."
+    if [ -f "$dir/pyproject.toml" ]; then
+      (cd "$dir" && pip install -q -e ".[dev]" 2>/dev/null) || (cd "$dir" && pip install -q -e .)
+    elif [ -f "$dir/requirements.txt" ]; then
+      (cd "$dir" && pip install -q -r requirements.txt)
+    elif [ -f "$dir/setup.py" ] || [ -f "$dir/setup.cfg" ]; then
+      (cd "$dir" && pip install -q -e .)
+    elif [ -f "$dir/Pipfile" ] && command -v pipenv >/dev/null 2>&1; then
+      (cd "$dir" && pipenv install --dev)
+      python_bin="$(cd "$dir" && pipenv --py)"
+    fi
+  fi
+
+  append_env "HARNESS_ECOSYSTEM" "python"
+  append_env "PYTHON_BIN" "$python_bin"
+  append_env "VIRTUAL_ENV" "$venv_dir"
+  append_path_prefix "$venv_dir/bin"
+}
+
+provision_go() {
+  local dir="$1"
+  if ! run_install_cmd "$dir"; then
+    if command -v go >/dev/null 2>&1; then
+      pt_log "Downloading Go modules..."
+      (cd "$dir" && go mod download)
+    else
+      pt_log "go not found on PATH — record paths only"
+    fi
+  fi
+  append_env "HARNESS_ECOSYSTEM" "go"
+  append_env "GO_BIN" "$(command -v go 2>/dev/null || echo go)"
+  if [ -n "${GOPATH:-}" ]; then append_env "GOPATH" "$GOPATH"; fi
+  if [ -n "${GOROOT:-}" ]; then append_env "GOROOT" "$GOROOT"; fi
+}
+
+provision_rust() {
+  local dir="$1"
+  if ! run_install_cmd "$dir"; then
+    if command -v cargo >/dev/null 2>&1; then
+      pt_log "Fetching Rust dependencies..."
+      (cd "$dir" && cargo fetch)
+    else
+      pt_log "cargo not found on PATH — record paths only"
+    fi
+  fi
+  append_env "HARNESS_ECOSYSTEM" "rust"
+  append_env "CARGO_BIN" "$(command -v cargo 2>/dev/null || echo cargo)"
+  append_env "RUSTC_BIN" "$(command -v rustc 2>/dev/null || echo rustc)"
+}
+
+provision_java() {
+  local dir="$1"
+  run_install_cmd "$dir" || true
+  append_env "HARNESS_ECOSYSTEM" "java"
+  if [ -n "${JAVA_HOME:-}" ]; then
+    append_env "JAVA_HOME" "$JAVA_HOME"
+    append_path_prefix "$JAVA_HOME/bin"
+  fi
+  if command -v mvn >/dev/null 2>&1; then
+    append_env "MVN_BIN" "$(command -v mvn)"
+  elif [ -f "$dir/gradlew" ]; then
+    append_env "GRADLE_BIN" "$dir/gradlew"
+  elif command -v gradle >/dev/null 2>&1; then
+    append_env "GRADLE_BIN" "$(command -v gradle)"
+  fi
+}
+
+provision_ruby() {
+  local dir="$1"
+  if ! run_install_cmd "$dir"; then
+    if command -v bundle >/dev/null 2>&1; then
+      pt_log "Installing Ruby gems..."
+      (cd "$dir" && bundle install --quiet)
+    else
+      pt_log "bundle not found on PATH — record paths only"
+    fi
+  fi
+  append_env "HARNESS_ECOSYSTEM" "ruby"
+  append_env "RUBY_BIN" "$(command -v ruby 2>/dev/null || echo ruby)"
+  append_env "BUNDLE_BIN" "$(command -v bundle 2>/dev/null || echo bundle)"
+  append_path_prefix "$dir/vendor/bundle/bin"
+}
+
+provision_ios() {
+  local dir="$1"
+  run_install_cmd "$dir" || true
+  append_env "HARNESS_ECOSYSTEM" "ios"
+  append_env "XCODEBUILD_BIN" "$(command -v xcodebuild 2>/dev/null || echo xcodebuild)"
+  if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then
+    append_env "HARNESS_XCODE_SCHEME" "$HARNESS_XCODE_SCHEME"
+  fi
+  if [ -n "${HARNESS_SIMULATOR_NAME:-}" ]; then
+    append_env "HARNESS_SIMULATOR_NAME" "$HARNESS_SIMULATOR_NAME"
+  fi
+  if [ -n "${HARNESS_BUNDLE_ID:-}" ]; then
+    append_env "HARNESS_BUNDLE_ID" "$HARNESS_BUNDLE_ID"
+  fi
+  if [ -n "${DEVELOPER_DIR:-}" ]; then
+    append_env "DEVELOPER_DIR" "$DEVELOPER_DIR"
+  fi
+}
+
+provision_monorepo_root() {
+  [ -n "$HAR_REL_PREFIX" ] || return 0
+  [ -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)
+}
+
+provision_ecosystem() {
+  local dir="$1"
+  local ecosystem
+  ecosystem="$(detect_ecosystem "$dir")"
+  pt_log "Toolchain ecosystem: ${ecosystem} (work dir: ${dir})"
+
+  case "$ecosystem" in
+    node) provision_node "$dir" ;;
+    python) provision_python "$dir" ;;
+    go) provision_go "$dir" ;;
+    rust) provision_rust "$dir" ;;
+    java) provision_java "$dir" ;;
+    ruby) provision_ruby "$dir" ;;
+    ios) provision_ios "$dir" ;;
+    none)
+      if run_install_cmd "$dir"; then
+        append_env "HARNESS_ECOSYSTEM" "custom"
+      else
+        pt_log "No ecosystem manifest detected — set HARNESS_ECOSYSTEM or HARNESS_INSTALL_CMD in harness.env"
+        append_env "HARNESS_ECOSYSTEM" "none"
+      fi
+      ;;
+  esac
+}
+
+append_env "HARNESS_TOOLCHAIN_PROVISIONED" "true"
+provision_ecosystem "$HAR_WORK_DIR"
+provision_monorepo_root

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

@@ -11,26 +11,101 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 COMPOSE_FILE="$SCRIPT_DIR/docker-compose.agent.yml"
+INFRA_STATE="$SCRIPT_DIR/state/infra.env"
 
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
 
 COMPOSE_PROJECT="har-${HARNESS_PROJECT_NAME}"
-DB_PORT="${AGENT_DB_PORT:-15432}"
 PSQL="har_pg psql -d postgres"
 
 log() { echo "==> $*" >&2; }
 
+har_compose_service_running() {
+  local service="$1"
+  docker ps --filter "name=${COMPOSE_PROJECT}-${service}-1" --format '{{.Names}}' 2>/dev/null \
+    | grep -q "^${COMPOSE_PROJECT}-${service}-1\$"
+}
+
+har_resolve_infra_port() {
+  local var_name="$1"
+  local default_port="$2"
+  local scan_start="$3"
+  local scan_end="$4"
+  local service="${5:-}"
+  local current="${!var_name:-}"
+
+  if [ -n "$current" ] && { ! port_in_use "$current" || { [ -n "$service" ] && har_compose_service_running "$service"; }; }; then
+    echo "$current"
+    return 0
+  fi
+  har_allocate_port "$default_port" "$scan_start" "$scan_end"
+}
+
+mkdir -p "$(dirname "$INFRA_STATE")"
+if [ -f "$INFRA_STATE" ]; then
+  # shellcheck source=/dev/null
+  source "$INFRA_STATE"
+fi
+
+DB_PORT="$(har_resolve_infra_port AGENT_DB_PORT \
+  "${HARNESS_DB_PORT_DEFAULT:-15432}" \
+  "${HARNESS_DB_PORT_SCAN_START:-15432}" \
+  "${HARNESS_DB_PORT_SCAN_END:-15499}" \
+  db)"
+MINIO_PORT="$(har_resolve_infra_port AGENT_MINIO_PORT \
+  "${HARNESS_MINIO_PORT_DEFAULT:-19000}" \
+  "${HARNESS_MINIO_PORT_SCAN_START:-19000}" \
+  "${HARNESS_MINIO_PORT_SCAN_END:-19099}" \
+  minio)"
+MINIO_CONSOLE_PORT="$(har_resolve_infra_port AGENT_MINIO_CONSOLE_PORT \
+  "${HARNESS_MINIO_CONSOLE_PORT_DEFAULT:-19001}" \
+  "${HARNESS_MINIO_CONSOLE_PORT_SCAN_START:-19001}" \
+  "${HARNESS_MINIO_CONSOLE_PORT_SCAN_END:-19099}")"
+BROWSER_PORT="$(har_resolve_infra_port AGENT_BROWSER_PORT \
+  "${HARNESS_BROWSER_PORT_DEFAULT:-13001}" \
+  "${HARNESS_BROWSER_PORT_SCAN_START:-13001}" \
+  "${HARNESS_BROWSER_PORT_SCAN_END:-13099}" \
+  headless-browser)"
+MAILPIT_WEB_PORT="$(har_resolve_infra_port AGENT_MAILPIT_WEB_PORT \
+  "${HARNESS_MAILPIT_WEB_PORT_DEFAULT:-18025}" \
+  "${HARNESS_MAILPIT_WEB_PORT_SCAN_START:-18025}" \
+  "${HARNESS_MAILPIT_WEB_PORT_SCAN_END:-18099}" \
+  mailpit)"
+MAILPIT_SMTP_PORT="$(har_resolve_infra_port AGENT_MAILPIT_SMTP_PORT \
+  "${HARNESS_MAILPIT_SMTP_PORT_DEFAULT:-11025}" \
+  "${HARNESS_MAILPIT_SMTP_PORT_SCAN_START:-11025}" \
+  "${HARNESS_MAILPIT_SMTP_PORT_SCAN_END:-11099}")"
+
+export AGENT_DB_PORT="$DB_PORT"
+export AGENT_MINIO_PORT="$MINIO_PORT"
+export AGENT_MINIO_CONSOLE_PORT="$MINIO_CONSOLE_PORT"
+export AGENT_BROWSER_PORT="$BROWSER_PORT"
+export AGENT_MAILPIT_WEB_PORT="$MAILPIT_WEB_PORT"
+export AGENT_MAILPIT_SMTP_PORT="$MAILPIT_SMTP_PORT"
+
+cat > "$INFRA_STATE" <<EOF
+# Persisted by setup-infra.sh — host ports for shared docker compose services.
+export AGENT_DB_PORT=${DB_PORT}
+export AGENT_MINIO_PORT=${MINIO_PORT}
+export AGENT_MINIO_CONSOLE_PORT=${MINIO_CONSOLE_PORT}
+export AGENT_BROWSER_PORT=${BROWSER_PORT}
+export AGENT_MAILPIT_WEB_PORT=${MAILPIT_WEB_PORT}
+export AGENT_MAILPIT_SMTP_PORT=${MAILPIT_SMTP_PORT}
+EOF
+
 SERVICES="${HARNESS_INFRA_SERVICES:-}"
 
 if [ -n "$SERVICES" ]; then
   log "Starting shared infrastructure (project: $COMPOSE_PROJECT): $SERVICES"
   AGENT_DB_PORT="$DB_PORT" \
-  AGENT_MINIO_PORT="${AGENT_MINIO_PORT:-19000}" \
-  AGENT_MINIO_CONSOLE_PORT="${AGENT_MINIO_CONSOLE_PORT:-19001}" \
-  AGENT_BROWSER_PORT="${AGENT_BROWSER_PORT:-13001}" \
-  AGENT_MAILPIT_WEB_PORT="${AGENT_MAILPIT_WEB_PORT:-18025}" \
-  AGENT_MAILPIT_SMTP_PORT="${AGENT_MAILPIT_SMTP_PORT:-11025}" \
+  AGENT_MINIO_PORT="$MINIO_PORT" \
+  AGENT_MINIO_CONSOLE_PORT="$MINIO_CONSOLE_PORT" \
+  AGENT_BROWSER_PORT="$BROWSER_PORT" \
+  AGENT_MAILPIT_WEB_PORT="$MAILPIT_WEB_PORT" \
+  AGENT_MAILPIT_SMTP_PORT="$MAILPIT_SMTP_PORT" \
     docker compose -p "$COMPOSE_PROJECT" -f "$COMPOSE_FILE" up -d $SERVICES
 else
   log "No shared infra services enabled in harness.env (HARNESS_INFRA_SERVICES)"
@@ -85,18 +160,19 @@ fi
 # Shared app services — supporting services of a monolith/monorepo that agents
 # depend on but do not modify. Started ONCE on fixed ports, shared by all slots.
 # Create .har/ecosystem.shared.config.cjs (PM2 format, processes named
-# "har-shared-<name>") only when the primary app needs sibling services running.
+# "har-${HARNESS_PROJECT_NAME}-shared-<name>") only when the primary app needs
+# sibling services running.
 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)
-  log "Shared app services running (pm2 ls | grep har-shared-)."
+  log "Shared app services running (pm2 ls | grep har-${HARNESS_PROJECT_NAME}-shared-)."
 fi
 
 echo ""
 log "Infrastructure is ready."
 har_infra_enabled db               && log "  PostgreSQL: localhost:$DB_PORT"
-har_infra_enabled minio            && log "  MinIO:      http://localhost:${AGENT_MINIO_CONSOLE_PORT:-19001}"
-har_infra_enabled headless-browser && log "  Browser:    http://localhost:${AGENT_BROWSER_PORT:-13001}"
-har_infra_enabled mailpit          && log "  Mailpit:    http://localhost:${AGENT_MAILPIT_WEB_PORT:-18025}"
+har_infra_enabled minio            && log "  MinIO:      http://localhost:${MINIO_CONSOLE_PORT}"
+har_infra_enabled headless-browser && log "  Browser:    http://localhost:${BROWSER_PORT}"
+har_infra_enabled mailpit          && log "  Mailpit:    http://localhost:${MAILPIT_WEB_PORT}"
 exit 0

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

@@ -4,9 +4,9 @@
 #
 # Usage: ./.har/verify.sh <agent-id> [--full]
 #
-# Quick (default): smoke — compile / typecheck / build only
-# Full (--full):   + unit tests, lint, optional readiness + browser-e2e
-# Step lists are examples — not exhaustive. Adapt commands to this repo's stack.
+# Quick (default): ecosystem smoke — compile/import/build only
+# Full (--full):   + conventional tests, lint, optional readiness + browser-e2e
+# Stock steps are examples. Replace them during adaptation to match this repo.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -61,7 +61,7 @@ run_step() {
   start=$(now_ms)
 
   set +e
-  output=$(cd "$WORK_DIR" && eval "$cmd" 2>&1)
+  output=$(cd "$WORK_DIR" && set -a && . "$ENV_FILE" && set +a && eval "$cmd" 2>&1)
   exit_code=$?
   set -e
 
@@ -93,16 +93,97 @@ process.stdout.write(JSON.stringify(arr));
   fi
 }
 
-# ── Quick (default): smoke only ──────────────────────────────────────────────
-# Customize for this repo: compile / import / build — not the full test suite.
-run_step "typecheck" "npm run typecheck" || { [ -z "$FULL" ] && true; }
-# Some unit tests exec dist/index.js (e.g. stage-templates CLI add-stage).
-run_step "build" "npm run build" || { [ -z "$FULL" ] && true; }
+node_package_script_exists() {
+  local script="$1"
+  "${NODE_BIN:-node}" -e "
+const fs = require('fs');
+const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const script = process.argv[1];
+process.exit(pkg.scripts && pkg.scripts[script] ? 0 : 1);
+" "$script"
+}
+
+run_node_script_or_skip() {
+  local name="$1"
+  local script="$2"
+  if node_package_script_exists "$script"; then
+    run_step "$name" "${NPM_BIN:-npm} run ${script}"
+  else
+    run_step "$name" "echo 'No ${script} script configured; skipping.'"
+  fi
+}
+
+run_node_quick_smoke() {
+  if node_package_script_exists typecheck; then
+    run_step "node-typecheck" '${NPM_BIN:-npm} run typecheck'
+  elif node_package_script_exists build; then
+    run_step "node-build" '${NPM_BIN:-npm} run build'
+  else
+    run_step "node-package-load" '${NODE_BIN:-node} -e "require(\"./package.json\")"'
+  fi
+}
+
+run_quick_smoke() {
+  case "${HARNESS_ECOSYSTEM:-none}" in
+    node)
+      run_node_quick_smoke
+      ;;
+    python)
+      run_step "python-compile" '${PYTHON_BIN:-python3} -m compileall -q .'
+      ;;
+    go)
+      run_step "go-build" '${GO_BIN:-go} build ./...'
+      ;;
+    rust)
+      run_step "rust-check" '${CARGO_BIN:-cargo} check'
+      ;;
+    java)
+      run_step "java-compile" 'if [ -x ./mvnw ]; then ./mvnw -q -DskipTests compile; elif command -v mvn >/dev/null 2>&1; then mvn -q -DskipTests compile; elif [ -x ./gradlew ]; then ./gradlew classes; elif command -v gradle >/dev/null 2>&1; then gradle classes; else echo "No Maven/Gradle command found; adapt verify.sh for this Java repo."; fi'
+      ;;
+    ruby)
+      run_step "ruby-smoke" '${RUBY_BIN:-ruby} -e "puts RUBY_VERSION"'
+      ;;
+    custom|none|*)
+      run_step "smoke-not-configured" 'echo "No stock smoke for HARNESS_ECOSYSTEM=${HARNESS_ECOSYSTEM:-none}; adapt .har/verify.sh for this repo."'
+      ;;
+  esac
+}
+
+run_full_checks() {
+  case "${HARNESS_ECOSYSTEM:-none}" in
+    node)
+      run_node_script_or_skip "unit-tests" test || true
+      run_node_script_or_skip "lint" lint || true
+      ;;
+    python)
+      run_step "unit-tests" 'if ${PYTHON_BIN:-python3} -c "import pytest" >/dev/null 2>&1; then ${PYTHON_BIN:-python3} -m pytest -q; else echo "pytest not installed; adapt verify.sh for this Python repo."; fi' || true
+      ;;
+    go)
+      run_step "unit-tests" '${GO_BIN:-go} test ./...' || true
+      ;;
+    rust)
+      run_step "unit-tests" '${CARGO_BIN:-cargo} test' || true
+      ;;
+    java)
+      run_step "unit-tests" 'if [ -x ./mvnw ]; then ./mvnw -q test; elif command -v mvn >/dev/null 2>&1; then mvn -q test; elif [ -x ./gradlew ]; then ./gradlew test; elif command -v gradle >/dev/null 2>&1; then gradle test; else echo "No Maven/Gradle command found; adapt verify.sh for this Java repo."; fi' || true
+      ;;
+    ruby)
+      run_step "unit-tests" 'if command -v "${BUNDLE_BIN:-bundle}" >/dev/null 2>&1 && [ -f Gemfile ]; then "${BUNDLE_BIN:-bundle}" exec rake test 2>/dev/null || "${BUNDLE_BIN:-bundle}" exec rspec; else echo "No Ruby test command detected; adapt verify.sh for this Ruby repo."; fi' || true
+      ;;
+    custom|none|*)
+      run_step "unit-tests" 'echo "No stock full checks for HARNESS_ECOSYSTEM=${HARNESS_ECOSYSTEM:-none}; adapt .har/verify.sh for this repo."' || true
+      ;;
+  esac
+}
+
+# ── Verification stages ─────────────────────────────────────────────────────
+# These stock steps are intentionally generic conventions. Adapt this section
+# to the repository's real commands from package.json, Makefile, CI, pyproject,
+# Cargo.toml, go.mod, pom.xml, etc.
+run_quick_smoke || { [ -z "$FULL" ] && true; }
 
 if [ -n "$FULL" ]; then
-  # ── Full: project-specific checks (examples — add/remove/reorder as needed) ─
-  run_step "unit-tests" "npm test" || true
-  run_step "lint" "npm run lint" || true
+  run_full_checks
   run_step "readiness" "run_readiness_if_configured \"$AGENT_ID\"" || true
   run_step "browser-e2e" "run_browser_e2e_if_present \"$SCRIPT_DIR\" \"$AGENT_ID\"" || true
 fi

package/dist/templates/har-boilerplate-ios/README.md

@@ -12,14 +12,15 @@ Generated and maintained by [`har`](https://github.com/antoineFrau/har). Run `ha
 |------|---------|
 | `README.md` | This file — index of the harness |
 | `manifest.json` | Generator metadata (version, profile, checksums) — do not edit |
-| `harness.env` | Shared config: Xcode scheme, simulator name, bundle ID, infra flags |
+| `harness.env` | Shared config: Xcode scheme, simulator name, bundle ID, toolchain provisioning, infra flags |
 | `stages.json` | Machine-readable registry of runnable harness stages |
 | `stages/` | Optional custom stage scripts registered from `stages.json` |
 | `runs/` | Run history from `har env` / MCP — gitignored |
 | `artifacts/` | Stage outputs: test results, screenshots, logs |
 | `agent-slot.sh` | Shared agent-id validation and slot registry helpers |
 | `setup-infra.sh` | Boot the iOS Simulator; start optional Docker services |
-| `launch.sh` | Launch one agent slot (git worktree, CocoaPods/SPM deps, env file) |
+| `launch.sh` | Launch one agent slot (git worktree, toolchain provisioning, env file) |
+| `provision-toolchain.sh` | Write Xcode/simulator paths (`XCODEBUILD_BIN`, …) to `.env.agent.<id>` |
 | `verify.sh` | Verification pipeline (build smoke by default; --full adds tests, lint, flows) |
 | `teardown.sh` | Tear down one agent slot (worktree + env file) |
 | `agent-cli.sh` | Inspect slot status, run xcodebuild commands, install/launch app |
@@ -84,6 +85,32 @@ Edit **`harness.env`** to set:
 - `HARNESS_SIMULATOR_NAME` — target simulator (must be listed in `xcrun simctl list devices`)
 - `HARNESS_BUNDLE_ID` — app bundle identifier
 
+## Port & shared services (iOS profile)
+
+Pure iOS apps have **no per-slot TCP ports** — agents build and run on a shared iOS Simulator. Optional backend containers (mock API, etc.) use the same shared-infra model as other profiles.
+
+### Port allocation
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| Optional backend (compose) | Per machine | `HARNESS_*_PORT_DEFAULT` for that service | Scan configured ranges in `harness.env` |
+| iOS Simulator | Shared | No harness port — one booted simulator for all slots | N/A |
+
+When your app talks to a local backend, read the resolved host port from `.env.agent.<id>` (set by `setup-infra.sh`) — never hardcode `15432` or similar in tests or flow scripts.
+
+### Shared vs per-slot
+
+| Resource | Model | Configuration |
+|----------|-------|---------------|
+| iOS Simulator | One booted simulator shared by all slots | `HARNESS_SIMULATOR_NAME`, `setup-infra.sh` |
+| Optional backend | One shared compose service | `HARNESS_INFRA_SERVICES` (e.g. `"mock-server"`) |
+| Application code | Isolated git worktree per slot | `HARNESS_USE_WORKTREE=true` |
+
+### Do not
+
+- Hardcode backend ports in RocketSim flows or unit tests — read from agent env
+- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh`
+
 ## Session lifecycle
 
 Every `launch` starts a **fresh session**: a new git worktree from the current HEAD at

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

@@ -7,6 +7,10 @@ export HARNESS_USE_WORKTREE=true
 export HARNESS_AGENT_SLOT_MIN=1
 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 ..."
+
 # ── Xcode project ─────────────────────────────────────────────────────────────
 # Set one of HARNESS_XCODE_WORKSPACE or HARNESS_XCODE_PROJECT (workspace wins).
 export HARNESS_XCODE_WORKSPACE=""     # e.g. MyApp.xcworkspace (relative to repo root)
@@ -29,8 +33,9 @@ export HARNESS_IOS_DESTINATION="platform=iOS Simulator,name=${HARNESS_SIMULATOR_
 export HARNESS_SWIFTLINT_CMD="${HARNESS_SWIFTLINT_CMD:-swiftlint}"
 
 # ── Infrastructure ────────────────────────────────────────────────────────────
-# No Docker infra for pure iOS apps. Set a service name here (space-separated)
+# 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.
 export HARNESS_INFRA_SERVICES=""
 
 # Returns 0 when a shared infra service is enabled: har_infra_enabled mock-server