@osfactory/har 0.6.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/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-ios/README.md

@@ -85,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

@@ -33,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "LLM-powered CLI for reproducible agent development environments",
   "keywords": [
     "har",

package/dist/templates/har-boilerplate-ios/ADAPT-PROMPT.md

@@ -1,57 +0,0 @@
-# Adapt this iOS harness to the project
-
-You are adapting a freshly scaffolded iOS mobile app harness. Read the existing repo
-structure, then make the changes listed below. Commit when done.
-
-## 1 — Read before editing
-
-- `AGENT.md` at the repo root (overview and do-nots)
-- `.har/README.md` (harness index)
-- `.har/harness.env` (all config vars)
-- `.har/stages.json` (stage registry)
-- Root of the repo: look for `*.xcworkspace`, `*.xcodeproj`, `Podfile`, `Package.swift`
-
-## 2 — Set Xcode project config in `.har/harness.env`
-
-| Variable | What to set |
-|----------|-------------|
-| `HARNESS_XCODE_WORKSPACE` | Relative path to `.xcworkspace` (e.g. `MyApp.xcworkspace`). Use when CocoaPods or a workspace is present. Leave empty otherwise. |
-| `HARNESS_XCODE_PROJECT` | Relative path to `.xcodeproj` (e.g. `MyApp.xcodeproj`). Only set when no workspace. |
-| `HARNESS_XCODE_SCHEME` | Name of the shared Xcode scheme (must be marked Shared in Xcode → Product → Scheme → Manage Schemes). |
-| `HARNESS_SIMULATOR_NAME` | Display name exactly as shown in `xcrun simctl list devices` (e.g. `iPhone 16`). |
-| `HARNESS_BUNDLE_ID` | App bundle identifier from the Xcode target (e.g. `com.example.myapp`). |
-
-Run `./.har/setup-infra.sh` after editing to confirm the simulator boots.
-
-## 3 — Verify `.har/verify.sh` builds and tests correctly
-
-Run `./.har/launch.sh 1`, then `./.har/verify.sh 1`.
-
-Common adaptations:
-- If the project uses a custom test plan, add `-testPlan MyTests` to the `xcodebuild test` invocation.
-- If SwiftLint is not used, remove or comment out the `lint` step.
-- If there are UI tests that require a running app, move them to a RocketSim flow (`har env add-stage rocketsim`) rather than xcodebuild tests.
-
-## 4 — Add the RocketSim stage template (recommended)
-
-```bash
-har env add-stage rocketsim
-```
-
-Then adapt `flows/example-smoke.sh` to navigate to your app's main screen and verify it loads.
-Read `.har/stages/ROCKETSIM.md` for the full authoring guide.
-
-## 5 — Update `AGENT.md` (repo root)
-
-Replace the TODO section with:
-- Which Xcode scheme and simulator are used
-- How to run unit tests manually
-- How to add a new RocketSim user flow
-
-## 6 — Verify everything passes
-
-```bash
-./.har/verify.sh 1 --full
-```
-
-All steps should return ✓. Commit the adapted harness in the session worktree.