@osfactory/har 0.1.1

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

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# Shared slot helpers: agent-id validation, slot registry, work-dir resolution.
+# Source after harness.env (requires $SCRIPT_DIR pointing at the .har directory):
+#   source "$SCRIPT_DIR/harness.env"
+#   source "$SCRIPT_DIR/agent-slot.sh"
+#   validate_agent_id "$AGENT_ID"
+
+validate_agent_id() {
+  local id="${1:-}"
+  local min="${HARNESS_AGENT_SLOT_MIN:-1}"
+  local max="${HARNESS_AGENT_SLOT_MAX:-}"
+
+  if [[ -z "$max" ]]; then
+    echo "Error: HARNESS_AGENT_SLOT_MAX is not set in harness.env" >&2
+    exit 1
+  fi
+
+  if [[ -z "$id" ]] || ! [[ "$id" =~ ^[0-9]+$ ]]; then
+    echo "Error: agent-id must be a positive integer between ${min} and ${max}" >&2
+    exit 1
+  fi
+
+  if (( id < min || id > max )); then
+    echo "Error: agent-id must be between ${min} and ${max}" >&2
+    exit 1
+  fi
+}
+
+# ── Slot registry ─────────────────────────────────────────────────────────────
+# .har/slots/agent-<id>.json is the source of truth for where a session lives
+# (worktree path, work dir, branch, base commit). Written by launch.sh, removed
+# by teardown.sh. Location resolution must go through it — worktree paths carry
+# a random per-session suffix and cannot be derived from the agent id alone.
+
+slot_registry_file() {
+  echo "${SCRIPT_DIR}/slots/agent-${1}.json"
+}
+
+# read_slot_field <registry-file> <field> — echoes the scalar value, empty if absent.
+read_slot_field() {
+  [ -f "${1:-}" ] || return 1
+  node -e '
+try {
+  const v = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))[process.argv[2]];
+  if (v != null && typeof v !== "object") process.stdout.write(String(v));
+} catch {}
+' "$1" "$2"
+}
+
+# Writes the registry entry from SLOT_* variables:
+#   required: SLOT_AGENT_ID, SLOT_MODE (worktree|root), SLOT_WORK_DIR
+#   optional: SLOT_SUFFIX, SLOT_WORKTREE_PATH, SLOT_BRANCH, SLOT_BASE_BRANCH,
+#             SLOT_BASE_COMMIT, SLOT_PORTS_JSON, SLOT_PREVIEW_URLS_JSON, SLOT_PURPOSE
+write_slot_registry() {
+  local file
+  file="$(slot_registry_file "$SLOT_AGENT_ID")"
+  mkdir -p "$(dirname "$file")"
+  node -e '
+const fs = require("fs");
+const e = process.env;
+const entry = {
+  version: 1,
+  agentId: Number(e.SLOT_AGENT_ID),
+  projectName: e.HARNESS_PROJECT_NAME || "",
+  mode: e.SLOT_MODE,
+  workDir: e.SLOT_WORK_DIR,
+  createdAt: new Date().toISOString(),
+  status: "active",
+};
+if (e.SLOT_SUFFIX) entry.suffix = e.SLOT_SUFFIX;
+if (e.SLOT_WORKTREE_PATH) entry.worktreePath = e.SLOT_WORKTREE_PATH;
+if (e.SLOT_BRANCH) entry.branch = e.SLOT_BRANCH;
+if (e.SLOT_BASE_BRANCH) entry.baseBranch = e.SLOT_BASE_BRANCH;
+if (e.SLOT_BASE_COMMIT) entry.baseCommit = e.SLOT_BASE_COMMIT;
+if (e.SLOT_PURPOSE) entry.purpose = e.SLOT_PURPOSE;
+for (const [key, env] of [["ports", "SLOT_PORTS_JSON"], ["previewUrls", "SLOT_PREVIEW_URLS_JSON"]]) {
+  if (e[env]) try { entry[key] = JSON.parse(e[env]); } catch {}
+}
+fs.writeFileSync(process.argv[1], JSON.stringify(entry, null, 2) + "\n");
+' "$file"
+}
+
+remove_slot_registry() {
+  rm -f "$(slot_registry_file "$1")"
+}
+
+# Exit 0 when the worktree has uncommitted or untracked changes.
+slot_worktree_dirty() {
+  [ -d "${1:-}" ] || return 1
+  [ -n "$(git -C "$1" status --porcelain 2>/dev/null)" ]
+}
+
+# Exit 0 when a slot registry entry or worktree path exists for this agent id.
+slot_is_occupied() {
+  local agent_id="$1"
+  [ -f "$(slot_registry_file "$agent_id")" ] || [ -n "$(existing_slot_worktree "$agent_id")" ]
+}
+
+# Echo "clean" or "dirty (N changed)" for a worktree path.
+slot_dirty_summary() {
+  local wt="${1:-}"
+  if [ -z "$wt" ] || [ ! -d "$wt" ]; then
+    echo "unknown"
+    return 0
+  fi
+  if ! slot_worktree_dirty "$wt"; then
+    echo "clean"
+    return 0
+  fi
+  local count
+  count="$(git -C "$wt" status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
+  echo "dirty (${count} changed)"
+}
+
+# Print a warning before replacing an occupied slot (stdout — visible to agents).
+print_slot_replace_warning() {
+  local agent_id="$1"
+  local reg wt branch work_dir purpose created dirty_summary head
+  reg="$(slot_registry_file "$agent_id")"
+  wt="$(existing_slot_worktree "$agent_id")"
+  branch="$(read_slot_field "$reg" branch || true)"
+  work_dir="$(read_slot_field "$reg" workDir || true)"
+  purpose="$(read_slot_field "$reg" purpose || true)"
+  created="$(read_slot_field "$reg" createdAt || true)"
+  dirty_summary="$(slot_dirty_summary "$wt")"
+  if [ -n "$wt" ] && [ -d "$wt" ]; then
+    head="$(git -C "$wt" rev-parse --short HEAD 2>/dev/null || true)"
+  fi
+
+  echo "" >&2
+  echo "⚠ Slot ${agent_id} is already in use — replacing will REMOVE the worktree." >&2
+  [ -n "$purpose" ] && echo "  Purpose:   ${purpose}" >&2
+  [ -n "$wt" ] && echo "  Worktree:  ${wt}" >&2
+  [ -n "$work_dir" ] && echo "  Work dir:  ${work_dir}" >&2
+  [ -n "$branch" ] && echo "  Branch:    ${branch}${head:+ @ ${head}}" >&2
+  [ -n "$created" ] && echo "  Since:     ${created}" >&2
+  echo "  Git:       ${dirty_summary}" >&2
+  echo "" >&2
+  echo "  The session branch is kept only if you committed. Gitignored paths" >&2
+  echo "  (state/, runs/, local clones, .env.local) are NOT preserved." >&2
+  echo "" >&2
+}
+
+# Require explicit confirmation before replacing an occupied slot.
+#   $1 agent_id  $2 force(true/false)  $3 replace(true/false)
+# Exits 1 when replacement must not proceed.
+require_slot_replace_confirm() {
+  local agent_id="$1"
+  local force="$2"
+  local replace="$3"
+  local wt
+
+  slot_is_occupied "$agent_id" || return 0
+
+  print_slot_replace_warning "$agent_id"
+  wt="$(existing_slot_worktree "$agent_id")"
+
+  if [ -n "$wt" ] && slot_worktree_dirty "$wt" && [ "$force" != true ]; then
+    echo "ERROR: previous session for slot ${agent_id} has uncommitted changes." >&2
+    echo "  Commit them in the worktree (branch is kept on teardown), or pass --force to discard." >&2
+    echo "  --force destroys uncommitted work — only use after explicit user approval." >&2
+    exit 1
+  fi
+
+  if [ "$replace" = true ] || [ "${HAR_CONFIRM_REPLACE:-}" = "1" ]; then
+    return 0
+  fi
+
+  if [ -t 0 ] && [ -t 1 ]; then
+    local answer
+    read -r -p "Replace slot ${agent_id}? Uncommitted work is lost unless committed. [y/N] " answer
+    if [[ "$answer" =~ ^[Yy]$ ]]; then
+      return 0
+    fi
+    echo "Aborted — slot ${agent_id} left unchanged." >&2
+    exit 2
+  fi
+
+  echo "ERROR: slot ${agent_id} is occupied." >&2
+  echo "  Pass --replace (or set HAR_CONFIRM_REPLACE=1) after reviewing the warning above." >&2
+  echo "  If the worktree is dirty, also pass --force (only after explicit user approval)." >&2
+  exit 2
+}
+
+# Echo the previous session's worktree path for a slot: registry first, then
+# the legacy fixed path (pre-registry sessions). Empty output when none exists.
+existing_slot_worktree() {
+  local agent_id="$1"
+  local reg path
+  reg="$(slot_registry_file "$agent_id")"
+  if [ -f "$reg" ]; then
+    path="$(read_slot_field "$reg" worktreePath || true)"
+    if [ -n "$path" ] && [ -d "$path" ]; then
+      echo "$path"
+      return 0
+    fi
+  fi
+  path="$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${agent_id}"
+  if [ -d "$path" ]; then
+    echo "$path"
+  fi
+  return 0
+}
+
+# Resolve .env.agent.<id> — registry work dir first, then legacy locations
+# (repo root, pre-registry fixed worktree path).
+resolve_agent_env_file() {
+  local agent_id="$1"
+  local repo_root="$2"
+  local reg work_dir
+  reg="$(slot_registry_file "$agent_id")"
+  if [ -f "$reg" ]; then
+    work_dir="$(read_slot_field "$reg" workDir || true)"
+    if [ -n "$work_dir" ] && [ -f "$work_dir/.env.agent.${agent_id}" ]; then
+      echo "$work_dir/.env.agent.${agent_id}"
+      return 0
+    fi
+  fi
+  # Worktrees are repo-rooted — if the project lives in a subdirectory (monorepo),
+  # the env file sits under that prefix inside the worktree.
+  local rel_prefix
+  rel_prefix="$(git -C "$repo_root" rev-parse --show-prefix 2>/dev/null || true)"
+  local candidate
+  for candidate in \
+    "$repo_root/.env.agent.${agent_id}" \
+    "$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${agent_id}/${rel_prefix}.env.agent.${agent_id}"; do
+    if [ -f "$candidate" ]; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Resolve work dir for verify/e2e — registry first, else the agent env file's
+# variables (call after sourcing the env file). Optional 2nd arg: agent id.
+resolve_agent_work_dir() {
+  local env_file="$1"
+  local agent_id="${2:-${AGENT_ID:-}}"
+  if [ -n "$agent_id" ]; then
+    local reg wd
+    reg="$(slot_registry_file "$agent_id")"
+    if [ -f "$reg" ]; then
+      wd="$(read_slot_field "$reg" workDir || true)"
+      if [ -n "$wd" ] && [ -d "$wd" ]; then
+        echo "$wd"
+        return 0
+      fi
+    fi
+  fi
+  local work_dir="${REPO_ROOT:-}"
+  if [ -z "$work_dir" ] || [ ! -d "$work_dir" ]; then
+    if [ -n "${WORKTREE_DIR:-}" ] && [ -d "$WORKTREE_DIR" ]; then
+      work_dir="$WORKTREE_DIR"
+    else
+      work_dir="$(cd "$(dirname "$env_file")" && pwd)"
+    fi
+  fi
+  echo "$work_dir"
+}
+
+# Run browser-e2e on verify --full when the Playwright stage template is installed.
+run_browser_e2e_if_present() {
+  local script_dir="$1"
+  local agent_id="$2"
+  local e2e="$script_dir/stages/browser-e2e.sh"
+  if [ -x "$e2e" ]; then
+    "$e2e" "$agent_id"
+  fi
+}

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

@@ -0,0 +1,17 @@
+version: "3.8"
+# Add backend services needed by your iOS app here.
+# Example: a mock API server or a local database.
+#
+# List services in HARNESS_INFRA_SERVICES in harness.env to enable them.
+# They start once on fixed ports and are shared by all agent slots.
+#
+# services:
+#   mock-server:
+#     image: stoplight/prism:4
+#     command: mock -h 0.0.0.0 /api/openapi.yaml
+#     ports:
+#       - "4010:4010"
+#     volumes:
+#       - ../api:/api:ro
+
+services: {}

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

@@ -0,0 +1,42 @@
+# iOS mobile app harness — Xcode / iOS Simulator, no PM2, no Docker infra
+# Generated by har env init --profile ios
+
+export HARNESS_PROJECT_NAME=__PROJECT_NAME__
+export HARNESS_USE_WORKTREE=true
+
+export HARNESS_AGENT_SLOT_MIN=1
+export HARNESS_AGENT_SLOT_MAX=3
+
+# ── 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)
+export HARNESS_XCODE_PROJECT=""       # e.g. MyApp.xcodeproj (relative to repo root)
+
+# Xcode scheme to build and test (must be marked as shared in Xcode).
+export HARNESS_XCODE_SCHEME="MyApp"
+
+# iOS Simulator to target. Use: xcrun simctl list devices | grep Booted
+# Common values: "iPhone 16", "iPhone 16 Pro", "iPhone SE (3rd generation)"
+export HARNESS_SIMULATOR_NAME="iPhone 16"
+
+# Bundle ID of the app under test. Used by setup-infra.sh / RocketSim flows.
+export HARNESS_BUNDLE_ID="com.example.myapp"
+
+# Derived xcodebuild destination string — override only if targeting a specific UDID.
+export HARNESS_IOS_DESTINATION="platform=iOS Simulator,name=${HARNESS_SIMULATOR_NAME}"
+
+# Optional SwiftLint path (leave empty to use system-installed swiftlint).
+export HARNESS_SWIFTLINT_CMD="${HARNESS_SWIFTLINT_CMD:-swiftlint}"
+
+# ── Infrastructure ────────────────────────────────────────────────────────────
+# No Docker infra for pure iOS apps. Set a service name here (space-separated)
+# only if your app needs a local backend container (e.g. a mock server).
+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
+}

package/dist/templates/har-boilerplate-ios/justfile

@@ -0,0 +1,33 @@
+# Agent harness shortcuts — requires `just` (https://github.com/casey/just)
+
+set shell := ["bash", "-cu"]
+
+setup:
+    ./setup-infra.sh
+
+launch id:
+    ./launch.sh {{id}}
+
+teardown id:
+    ./teardown.sh {{id}}
+
+verify id:
+    ./verify.sh {{id}}
+
+verify-full id:
+    ./verify.sh {{id}} --full
+
+status:
+    #!/usr/bin/env bash
+    for id in 1 2 3; do
+        ./agent-cli.sh "$id" status 2>/dev/null || true
+    done
+
+cli id cmd *args:
+    ./agent-cli.sh {{id}} {{cmd}} {{args}}
+
+simulator:
+    xcrun simctl list devices available | grep -E 'iPhone|iPad' | head -20
+
+flows id:
+    ./stages/rocketsim-flows.sh {{id}}

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Launch an agent slot for iOS mobile app repos (git worktree by default).
+# Every launch starts a FRESH session: any previous session for the slot is torn
+# down (its branch is kept) and a new suffixed worktree is created from HEAD.
+#
+# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--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:-}"
+USE_WORKTREE="${HARNESS_USE_WORKTREE:-true}"
+FORCE=false
+REPLACE=false
+PURPOSE="${HAR_SESSION_PURPOSE:-}"
+
+for arg in "$@"; do
+  case "$arg" in
+    --no-worktree) USE_WORKTREE=false ;;
+    --worktree) USE_WORKTREE=true ;;
+    --replace)  REPLACE=true ;;
+    --force)    FORCE=true ;;
+    --purpose=*) PURPOSE="${arg#--purpose=}" ;;
+  esac
+done
+
+if [[ -z "$AGENT_ID" ]]; then
+  echo "Usage: $0 <agent-id> [--no-worktree] [--replace] [--force] [--purpose=label]" >&2
+  echo "  agent-id must be between ${HARNESS_AGENT_SLOT_MIN} and ${HARNESS_AGENT_SLOT_MAX}" >&2
+  exit 1
+fi
+
+validate_agent_id "$AGENT_ID"
+
+log() { echo "==> [agent-$AGENT_ID] $*" >&2; }
+
+# Replace any previous session for this slot — requires explicit confirmation.
+if slot_is_occupied "$AGENT_ID"; then
+  require_slot_replace_confirm "$AGENT_ID" "$FORCE" "$REPLACE"
+  log "Replacing previous session for slot ${AGENT_ID}..."
+  "$SCRIPT_DIR/teardown.sh" "$AGENT_ID" >&2
+fi
+
+"$SCRIPT_DIR/setup-infra.sh"
+
+# Session worktree (default — use --no-worktree to work in repo root).
+# Name encodes what the session is based on: <base-branch>-<sha4>-har-agent-<id>-<rand4>.
+WORK_DIR="$REPO_ROOT"
+WORKTREE_DIR=""
+BRANCH=""
+SUFFIX=""
+BASE_BRANCH="$(git -C "$REPO_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "detached")"
+BASE_COMMIT="$(git -C "$REPO_ROOT" rev-parse HEAD 2>/dev/null || true)"
+if [ "$USE_WORKTREE" = true ]; then
+  SHORT_SHA="$(git -C "$REPO_ROOT" rev-parse --short=4 HEAD)"
+  SUFFIX="$(LC_ALL=C tr -dc 'a-z0-9' </dev/urandom 2>/dev/null | head -c 4 || true)"
+  [ -n "$SUFFIX" ] || SUFFIX="$(printf '%04d' $(( RANDOM % 10000 )))"
+  SESSION_NAME="${BASE_BRANCH//\//-}-${SHORT_SHA}-har-agent-${AGENT_ID}-${SUFFIX}"
+  BRANCH="$SESSION_NAME"
+  WORKTREE_DIR="$HOME/worktrees/${SESSION_NAME}"
+  log "Creating session worktree at $WORKTREE_DIR (branch $BRANCH)..."
+  git -C "$REPO_ROOT" worktree add "$WORKTREE_DIR" -b "$BRANCH"
+  # Worktrees are always rooted at the git repo — if this project lives in a
+  # subdirectory (monorepo), point WORK_DIR at the project inside the worktree.
+  REL_PREFIX="$(git -C "$REPO_ROOT" rev-parse --show-prefix 2>/dev/null || true)"
+  WORK_DIR="${WORKTREE_DIR%/}/${REL_PREFIX}"
+  WORK_DIR="${WORK_DIR%/}"
+else
+  log "Using repo root (worktree disabled)"
+fi
+
+# Keep harness-generated files out of accidental `git add -A` commits in repos
+# whose .gitignore doesn't know about har (applies to all worktrees too).
+GIT_EXCLUDE="$(git -C "$REPO_ROOT" rev-parse --git-common-dir 2>/dev/null)/info/exclude"
+if [ -n "$GIT_EXCLUDE" ] && [ -d "$(dirname "$GIT_EXCLUDE")" ]; then
+  for pattern in '.env.agent.*' 'ecosystem.agent.*.config.cjs'; do
+    grep -qxF "$pattern" "$GIT_EXCLUDE" 2>/dev/null || echo "$pattern" >> "$GIT_EXCLUDE"
+  done
+fi
+
+ENV_FILE="$WORK_DIR/.env.agent.${AGENT_ID}"
+log "Generating $ENV_FILE..."
+cat > "$ENV_FILE" <<EOF
+# Agent environment — generated by launch.sh
+AGENT_ID=${AGENT_ID}
+REPO_ROOT=${WORK_DIR}
+WORKTREE_DIR=${WORKTREE_DIR}
+NODE_ENV=test
+EOF
+
+if [ -f "$WORK_DIR/package.json" ]; then
+  log "Installing dependencies..."
+  (cd "$WORK_DIR" && npm install --silent)
+elif [ -f "$WORK_DIR/go.mod" ]; then
+  log "Go module detected in work dir (run go mod download if needed)"
+fi
+
+# Monorepo: file:/workspace deps may resolve modules from the repo root — install there too
+if [ -n "${REL_PREFIX:-}" ] && [ -f "$WORKTREE_DIR/package.json" ] && [ ! -d "$WORKTREE_DIR/node_modules" ]; then
+  log "Installing monorepo root dependencies in $WORKTREE_DIR..."
+  (cd "$WORKTREE_DIR" && npm install --silent)
+fi
+
+# Record the session in the slot registry — the source of truth for where
+# this slot's code lives (status/verify/teardown resolve through it).
+SLOT_AGENT_ID="$AGENT_ID" \
+SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+SLOT_WORK_DIR="$WORK_DIR" \
+SLOT_SUFFIX="${SUFFIX:-}" \
+SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+SLOT_BRANCH="${BRANCH:-}" \
+SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+SLOT_PURPOSE="${PURPOSE}" \
+  write_slot_registry
+
+log "Agent $AGENT_ID is ready."
+log ""
+log "  WORK DIR (make ALL file edits under this path — never the main checkout):"
+log "    ${WORK_DIR}"
+if [ "$USE_WORKTREE" = true ]; then
+  log "  Branch:    ${BRANCH} (based on ${BASE_BRANCH} @ ${BASE_COMMIT})"
+fi
+log ""
+log "  Verify:    ./.har/verify.sh $AGENT_ID"
+log "  Teardown:  ./.har/teardown.sh $AGENT_ID   (keeps the branch)"

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Sets up shared infrastructure for all iOS agent slots.
+# Boots the target iOS Simulator if not already running. No Docker required
+# for pure iOS apps — extend only when a local backend container is needed.
+# Idempotent — safe to run multiple times.
+#
+# Usage: ./.har/setup-infra.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+
+log() { echo "==> $*" >&2; }
+
+# ── Xcode check ───────────────────────────────────────────────────────────────
+if ! command -v xcodebuild >/dev/null 2>&1; then
+  echo "Error: xcodebuild not found — install Xcode from the App Store." >&2
+  exit 1
+fi
+
+XCODE_VERSION="$(xcodebuild -version 2>/dev/null | head -1 || echo 'Xcode (unknown)')"
+log "Found: $XCODE_VERSION"
+
+# ── Simulator ─────────────────────────────────────────────────────────────────
+SIMULATOR_NAME="${HARNESS_SIMULATOR_NAME:-iPhone 16}"
+
+log "Checking simulator: ${SIMULATOR_NAME}"
+
+UDID="$(xcrun simctl list devices available 2>/dev/null \
+  | grep "${SIMULATOR_NAME}" \
+  | grep -E '\([A-F0-9-]{36}\)' \
+  | head -1 \
+  | grep -oE '[A-F0-9-]{36}' \
+  | head -1 || true)"
+
+if [ -z "$UDID" ]; then
+  echo "Error: Simulator '${SIMULATOR_NAME}' not found in available devices." >&2
+  echo "  Available simulators:" >&2
+  xcrun simctl list devices available 2>/dev/null | grep -E 'iPhone|iPad' | head -20 >&2
+  echo "  Update HARNESS_SIMULATOR_NAME in .har/harness.env." >&2
+  exit 1
+fi
+
+STATE="$(xcrun simctl list devices 2>/dev/null \
+  | grep "$UDID" \
+  | grep -oE 'Booted|Shutdown|Unavailable' \
+  | head -1 || echo "unknown")"
+
+if [ "$STATE" = "Booted" ]; then
+  log "Simulator '${SIMULATOR_NAME}' ($UDID) is already booted."
+else
+  log "Booting simulator '${SIMULATOR_NAME}' ($UDID)..."
+  xcrun simctl boot "$UDID" 2>/dev/null || true
+
+  log "Waiting for simulator to become ready..."
+  for i in $(seq 1 30); do
+    CURRENT="$(xcrun simctl list devices 2>/dev/null | grep "$UDID" | grep -oE 'Booted' | head -1 || true)"
+    if [ "$CURRENT" = "Booted" ]; then
+      log "Simulator is ready."
+      break
+    fi
+    if [ "$i" = "30" ]; then
+      echo "Warning: Simulator did not reach Booted state within 30 seconds." >&2
+    fi
+    sleep 1
+  done
+fi
+
+# ── Optional Docker infra ─────────────────────────────────────────────────────
+SERVICES="${HARNESS_INFRA_SERVICES:-}"
+if [ -n "$SERVICES" ]; then
+  COMPOSE_FILE="$SCRIPT_DIR/docker-compose.agent.yml"
+  COMPOSE_PROJECT="har-${HARNESS_PROJECT_NAME}"
+  log "Starting shared infrastructure (project: $COMPOSE_PROJECT): $SERVICES"
+  docker compose -p "$COMPOSE_PROJECT" -f "$COMPOSE_FILE" up -d $SERVICES
+fi
+
+log ""
+log "Infrastructure is ready."
+log "  Simulator: ${SIMULATOR_NAME} ($UDID)"
+har_infra_enabled mock-server && log "  Mock server: running (see docker-compose.agent.yml)"
+exit 0

package/dist/templates/har-boilerplate-ios/stages/README.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Optional per-stage scripts live here.
+# Example: ./.har/stages/rocketsim-flows.sh <agent-id>
+#
+# Register custom stages in .har/stages.json with a project-owned command:
+#   "command": "./.har/stages/rocketsim-flows.sh {agentId}"
+#
+# To add the RocketSim user-flow stage template:
+#   har env add-stage rocketsim
+
+echo "Add stage scripts under .har/stages/ and register them in stages.json." >&2
+exit 1

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

@@ -0,0 +1,61 @@
+{
+  "version": "1",
+  "agentSlots": {
+    "min": 1,
+    "max": 3
+  },
+  "stages": [
+    {
+      "id": "setup-infra",
+      "kind": "setup",
+      "description": "Boot iOS Simulator and start optional shared infra",
+      "command": "./.har/setup-infra.sh"
+    },
+    {
+      "id": "launch",
+      "kind": "launch",
+      "description": "Prepare agent slot (git worktree, iOS deps, env file)",
+      "command": "./.har/launch.sh {agentId}",
+      "artifacts": [
+        {
+          "path": ".env.agent.{agentId}",
+          "kind": "file",
+          "description": "Generated per-agent environment file"
+        }
+      ]
+    },
+    {
+      "id": "verify",
+      "kind": "verify",
+      "description": "Verification pipeline (quick: build + unit-tests; --full adds lint + rocketsim-flows)",
+      "command": "./.har/verify.sh {agentId}",
+      "acceptsArgs": ["--full"],
+      "artifacts": [
+        {
+          "path": ".har/artifacts",
+          "kind": "directory",
+          "description": "Optional verification outputs (test results, screenshots)"
+        }
+      ]
+    },
+    {
+      "id": "status",
+      "kind": "inspect",
+      "description": "Inspect agent slot status, simulator, and worktree path",
+      "command": "./.har/agent-cli.sh {agentId} status",
+      "artifacts": [
+        {
+          "path": ".har/logs",
+          "kind": "directory",
+          "description": "Optional harness logs"
+        }
+      ]
+    },
+    {
+      "id": "teardown",
+      "kind": "teardown",
+      "description": "Remove worktree and env file for the slot",
+      "command": "./.har/teardown.sh {agentId}"
+    }
+  ]
+}