@osfactory/har 0.1.1

package/dist/templates/har-boilerplate-cli/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-cli/docker-compose.agent.yml

@@ -0,0 +1,64 @@
+# Shared infrastructure — ONE instance serves all agent slots (fixed ports).
+#
+# This file is a MENU of common external dependencies. When adapting:
+#   - DELETE services this project does not use (and their volumes)
+#   - ADD anything missing (redis, nats, keycloak, ...)
+# Only services listed in HARNESS_INFRA_SERVICES (harness.env) are started
+# by setup-infra.sh.
+services:
+  db:
+    image: pgvector/pgvector:pg16
+    restart: always
+    ports:
+      - "${AGENT_DB_PORT:-15432}:5432"
+    environment:
+      POSTGRES_PASSWORD: password
+    volumes:
+      - agent-db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    command:
+      - postgres
+      - -c
+      - shared_preload_libraries=pg_stat_statements
+      - -c
+      - pg_stat_statements.track=all
+    shm_size: 256m
+
+  minio:
+    image: coollabsio/minio:latest
+    ports:
+      - "${AGENT_MINIO_PORT:-19000}:9000"
+      - "${AGENT_MINIO_CONSOLE_PORT:-19001}:9001"
+    volumes:
+      - agent-minio-data:/minio/data
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+      MINIO_DEFAULT_BUCKETS: default,results
+      MINIO_BROWSER: "off"
+
+  headless-browser:
+    image: ghcr.io/browserless/chromium:v2.38.2
+    restart: always
+    ports:
+      - "${AGENT_BROWSER_PORT:-13001}:3000"
+    shm_size: 512m
+
+  mailpit:
+    image: axllent/mailpit:latest
+    restart: unless-stopped
+    ports:
+      - "${AGENT_MAILPIT_WEB_PORT:-18025}:8025"
+      - "${AGENT_MAILPIT_SMTP_PORT:-11025}:1025"
+    environment:
+      MP_MAX_MESSAGES: 5000
+      MP_SMTP_AUTH_ACCEPT_ANY: 1
+      MP_SMTP_AUTH_ALLOW_INSECURE: 1
+
+volumes:
+  agent-db-data:
+  agent-minio-data:

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

@@ -0,0 +1,40 @@
+# CLI / library harness — optional Docker via HARNESS_INFRA_SERVICES, no PM2
+# Generated by har env init --profile cli
+
+export HARNESS_PROJECT_NAME=__PROJECT_NAME__
+export HARNESS_USE_WORKTREE=true
+
+export HARNESS_FE_BASE_PORT=3000
+export HARNESS_API_BASE_PORT=8000
+export HARNESS_HEALTH_CHECK_PATH=
+
+export HARNESS_AGENT_SLOT_MIN=1
+export HARNESS_AGENT_SLOT_MAX=3
+
+# Shared infrastructure — space-separated docker compose service names from
+# docker-compose.agent.yml, started ONCE by setup-infra.sh and shared by all
+# agent slots on fixed ports. Empty = no containers. Prune/add services in the
+# 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
+}
+
+# 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"

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

@@ -0,0 +1,27 @@
+# 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}}

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Launch an agent slot for CLI/library repos (git worktree by default, optional Docker infra).
+# 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-cli/setup-infra.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Sets up shared infrastructure for all agents.
+# Starts the docker compose services listed in HARNESS_INFRA_SERVICES, creates
+# the template database (when "db" is enabled), and starts optional shared app
+# services (ecosystem.shared.config.cjs). One instance serves every agent slot.
+# Idempotent — safe to run multiple times.
+#
+# Usage: ./.har/setup-infra.sh
+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"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+
+COMPOSE_PROJECT="har-${HARNESS_PROJECT_NAME}"
+DB_PORT="${AGENT_DB_PORT:-15432}"
+PSQL="har_pg psql -d postgres"
+
+log() { echo "==> $*" >&2; }
+
+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}" \
+    docker compose -p "$COMPOSE_PROJECT" -f "$COMPOSE_FILE" up -d $SERVICES
+else
+  log "No shared infra services enabled in harness.env (HARNESS_INFRA_SERVICES)"
+fi
+
+# Wait for PostgreSQL and prepare the template database
+if har_infra_enabled db; then
+  log "Waiting for PostgreSQL on port $DB_PORT..."
+  for i in $(seq 1 30); do
+    if har_pg pg_isready -q 2>/dev/null; then
+      log "PostgreSQL is ready."
+      break
+    fi
+    if [ "$i" = "30" ]; then
+      echo "Error: PostgreSQL did not become ready within 30 seconds." >&2
+      exit 1
+    fi
+    sleep 1
+  done
+
+  log "Enabling pg_stat_statements extension..."
+  $PSQL -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements" 2>/dev/null || true
+
+  if [ -n "${HARNESS_TEMPLATE_DB:-}" ]; then
+    if $PSQL -tAc "SELECT 1 FROM pg_database WHERE datname = '$HARNESS_TEMPLATE_DB'" | grep -q 1; then
+      log "Template database '$HARNESS_TEMPLATE_DB' already exists. Skipping creation."
+    else
+      log "Creating template database '$HARNESS_TEMPLATE_DB'..."
+      $PSQL -c "CREATE DATABASE $HARNESS_TEMPLATE_DB"
+
+      if [ -n "${HARNESS_DB_MIGRATE_CMD:-}" ] && [ "$HARNESS_DB_MIGRATE_CMD" != "echo 'TODO: set migrate command'" ]; then
+        log "Running migrations..."
+        PGPASSWORD=password PGHOST=localhost PGPORT="$DB_PORT" PGUSER=postgres \
+          PGDATABASE="$HARNESS_TEMPLATE_DB" \
+          bash -c "cd '$REPO_ROOT' && $HARNESS_DB_MIGRATE_CMD"
+      fi
+
+      if [ -n "${HARNESS_DB_SEED_CMD:-}" ] && [ "$HARNESS_DB_SEED_CMD" != "echo 'TODO: set seed command'" ]; then
+        log "Running seeds..."
+        PGPASSWORD=password PGHOST=localhost PGPORT="$DB_PORT" PGUSER=postgres \
+          PGDATABASE="$HARNESS_TEMPLATE_DB" \
+          bash -c "cd '$REPO_ROOT' && $HARNESS_DB_SEED_CMD"
+      fi
+
+      log "Marking '$HARNESS_TEMPLATE_DB' as a PostgreSQL template..."
+      $PSQL -c "UPDATE pg_database SET datistemplate = true WHERE datname = '$HARNESS_TEMPLATE_DB'"
+      log "Template database ready: $HARNESS_TEMPLATE_DB"
+    fi
+  fi
+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.
+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-)."
+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}"
+exit 0

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

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Optional per-stage scripts live here.
+# Example: ./.har/stages/browser-e2e.sh <agent-id>
+#
+# Register custom stages in .har/stages.json with a project-owned command:
+#   "command": "./.har/stages/browser-e2e.sh {agentId}"
+
+echo "Add stage scripts under .har/stages/ and register them in stages.json." >&2
+exit 1