@osfactory/har 0.6.0 → 0.8.0

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

@@ -26,6 +26,357 @@ validate_agent_id() {
   fi
 }
 
+# ── Port allocation ─────────────────────────────────────────────────────────────
+# Try the configured default first; scan the slot lane or infra range when busy.
+
+port_in_use() {
+  local port="$1"
+  (exec 3<>"/dev/tcp/127.0.0.1/$port") 2>/dev/null && { exec 3>&- || true; return 0; }
+  return 1
+}
+
+har_port_step() {
+  echo "${HARNESS_PORT_STEP:-10}"
+}
+
+har_default_app_port() {
+  local base="$1"
+  local agent_id="$2"
+  echo $(( base + agent_id * $(har_port_step) ))
+}
+
+har_slot_port_lane_end() {
+  local default_port="$1"
+  echo $(( default_port + $(har_port_step) - 1 ))
+}
+
+# har_pick_free_port <start> <end> — echoes the first free port in [start, end].
+har_pick_free_port() {
+  local start="$1"
+  local end="$2"
+  local port
+  for ((port=start; port<=end; port++)); do
+    if ! port_in_use "$port"; then
+      echo "$port"
+      return 0
+    fi
+  done
+  echo "Error: no free port in range ${start}-${end}" >&2
+  return 1
+}
+
+# har_allocate_port <default> <scan_start> <scan_end>
+har_allocate_port() {
+  local default_port="$1"
+  local scan_start="$2"
+  local scan_end="$3"
+  if ! port_in_use "$default_port"; then
+    echo "$default_port"
+    return 0
+  fi
+  har_pick_free_port "$scan_start" "$scan_end"
+}
+
+# Allocate FE/API/DEBUG ports for a slot. Sets FE_PORT, API_PORT, DEBUG_PORT.
+har_allocate_slot_app_ports() {
+  local agent_id="$1"
+  local step fe_default api_default debug_default
+  step="$(har_port_step)"
+  fe_default="$(har_default_app_port "${HARNESS_FE_BASE_PORT}" "$agent_id")"
+  api_default="$(har_default_app_port "${HARNESS_API_BASE_PORT}" "$agent_id")"
+  debug_default=$(( 9200 + agent_id * step ))
+
+  FE_PORT="$(har_allocate_port "$fe_default" "$fe_default" "$(har_slot_port_lane_end "$fe_default")")"
+  API_PORT="$(har_allocate_port "$api_default" "$api_default" "$(har_slot_port_lane_end "$api_default")")"
+  DEBUG_PORT="$(har_allocate_port "$debug_default" "$debug_default" $(( debug_default + step - 1 )) )"
+  export FE_PORT API_PORT DEBUG_PORT
+}
+
+# ── Launch preflight (#36) ─────────────────────────────────────────────────────
+# Readiness gate before worktree/install — ports, foreign PM2, Docker conflicts.
+
+har_harness_uses_pm2() {
+  [ -f "${SCRIPT_DIR}/ecosystem.agent.template.cjs" ]
+}
+
+har_port_docker_occupant() {
+  local port="$1"
+  docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+    | grep -E ":${port}->|:${port}/" | head -1 | cut -f1 || true
+}
+
+# Detect port conflicts with `har control up` (Docker dashboard) — not project-specific;
+# warns when the customer's packaged Mission Control container shares a slot app port.
+har_check_control_port_conflict() {
+  local port="$1"
+  local name
+  name="$(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+    | grep -i control | grep -E ":${port}->|:${port}/" | head -1 | cut -f1 || true)"
+  if [ -n "$name" ]; then
+    echo "ERROR: har control up (container \"${name}\") occupies port ${port}." >&2
+    echo "  Run: har control down — or use a different agent slot." >&2
+    return 1
+  fi
+  return 0
+}
+
+har_warn_control_on_default_port() {
+  local agent_id="$1"
+  har_harness_uses_pm2 || return 0
+  local default_port
+  default_port="$(har_default_app_port "${HARNESS_FE_BASE_PORT:-3000}" "$agent_id")"
+  if [ "$FE_PORT" = "$default_port" ]; then
+    return 0
+  fi
+  local name
+  name="$(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+    | grep -i control | grep -E ":${default_port}->|:${default_port}/" | head -1 | cut -f1 || true)"
+  if [ -n "$name" ]; then
+    echo "WARN: har control up holds port ${default_port} (container \"${name}\")." >&2
+    echo "  Harness will use port ${FE_PORT} instead. Run: har control down — to reclaim the default port." >&2
+  fi
+}
+
+har_check_foreign_pm2() {
+  local agent_id="$1"
+  local pm2_raw
+  har_harness_uses_pm2 || return 0
+  pm2_raw="$(npx --yes pm2 jlist 2>/dev/null || true)"
+  [ -n "$pm2_raw" ] || return 0
+  set +e
+  echo "$pm2_raw" | node -e "
+const agentId = process.argv[1];
+const project = process.argv[2];
+const slotPrefix = 'har-' + project + '-agent-' + agentId + '-';
+const legacyPrefix = 'agent-' + agentId + '-';
+let raw = '';
+process.stdin.on('data', c => raw += c);
+process.stdin.on('end', () => {
+  try {
+    const arr = JSON.parse(raw);
+    if (!Array.isArray(arr)) process.exit(0);
+    const foreign = arr.filter(x =>
+      x.name && (
+        (x.name.startsWith('har-') && x.name.includes('-agent-' + agentId + '-') && !x.name.startsWith(slotPrefix)) ||
+        (x.name.startsWith(legacyPrefix) && !x.name.startsWith('har-'))
+      ));
+    if (foreign.length === 0) process.exit(0);
+    console.error('ERROR: foreign PM2 processes match agent ' + agentId + ':');
+    foreign.forEach(p => {
+      const cwd = p.pm2_env?.pm_cwd || p.pm2_env?.cwd || 'unknown';
+      console.error('  ' + p.name + '  cwd=' + cwd);
+    });
+    console.error('  Stop the other harness session or use a different slot.');
+    process.exit(1);
+  } catch {
+    process.exit(0);
+  }
+});
+" "$agent_id" "$HARNESS_PROJECT_NAME"
+  local rc=$?
+  set -e
+  return "$rc"
+}
+
+# ── Resume failed launch (#38) ───────────────────────────────────────────────
+
+slot_session_status() {
+  local agent_id="$1"
+  read_slot_field "$(slot_registry_file "$agent_id")" status || true
+}
+
+# Exit 0 when the slot registry records a partial launch (failed or starting).
+slot_is_resumable() {
+  local agent_id="$1"
+  local status
+  status="$(slot_session_status "$agent_id")"
+  [ "$status" = "failed" ] || [ "$status" = "starting" ]
+}
+
+# Echo shell assignments for launch.sh — eval after validating resumability.
+har_resume_session_assignments() {
+  local agent_id="$1"
+  local reg work_dir worktree branch suffix base_branch base_commit purpose mode env_file
+
+  if ! slot_is_resumable "$agent_id"; then
+    local status
+    status="$(slot_session_status "$agent_id")"
+    echo "echo \"ERROR: slot ${agent_id} is not resumable (status=${status:-none}; need failed or starting).\" >&2" >&2
+    echo "echo \"  Use a normal launch, or --replace to start a fresh session.\" >&2"
+    echo 'exit 2'
+    return 1
+  fi
+
+  reg="$(slot_registry_file "$agent_id")"
+  work_dir="$(read_slot_field "$reg" workDir || true)"
+  worktree="$(read_slot_field "$reg" worktreePath || true)"
+  branch="$(read_slot_field "$reg" branch || true)"
+  suffix="$(read_slot_field "$reg" suffix || true)"
+  base_branch="$(read_slot_field "$reg" baseBranch || true)"
+  base_commit="$(read_slot_field "$reg" baseCommit || true)"
+  purpose="$(read_slot_field "$reg" purpose || true)"
+  mode="$(read_slot_field "$reg" mode || true)"
+
+  if [ -z "$work_dir" ] || [ ! -d "$work_dir" ]; then
+    echo "echo \"ERROR: resume requires work dir from registry (missing or not found).\" >&2"
+    echo 'exit 1'
+    return 1
+  fi
+
+  env_file="$work_dir/.env.agent.${agent_id}"
+  if [ ! -f "$env_file" ]; then
+    echo "echo \"ERROR: resume requires env file: ${env_file}\" >&2"
+    echo 'exit 1'
+    return 1
+  fi
+
+  printf '%s\n' \
+    "WORK_DIR='${work_dir}'" \
+    "WORKTREE_DIR='${worktree}'" \
+    "BRANCH='${branch}'" \
+    "SUFFIX='${suffix}'" \
+    "BASE_BRANCH='${base_branch}'" \
+    "BASE_COMMIT='${base_commit}'" \
+    "PURPOSE='${purpose}'" \
+    "USE_WORKTREE=$([ "$mode" = worktree ] && echo true || echo false)" \
+    "ENV_FILE='${env_file}'"
+}
+
+# Skip provision-toolchain when deps were installed before the failed step.
+har_toolchain_ready() {
+  local work_dir="$1"
+  if [ -f "$work_dir/package.json" ] && [ -d "$work_dir/node_modules" ]; then
+    return 0
+  fi
+  if [ -d "$work_dir/.har/venv" ]; then
+    return 0
+  fi
+  return 1
+}
+
+# Rewrite agent env from env.template when ports changed during resume preflight.
+har_regenerate_agent_env_file() {
+  local agent_id="$1"
+  local work_dir="$2"
+  local env_file="$3"
+  local template="${SCRIPT_DIR}/env.template"
+  if [ ! -f "$template" ]; then
+    return 0
+  fi
+  AGENT_ID="$agent_id" \
+  API_PORT="$API_PORT" \
+  FE_PORT="$FE_PORT" \
+  DEBUG_PORT="$DEBUG_PORT" \
+  DB_PORT="${DB_PORT:-${AGENT_DB_PORT:-${HARNESS_DB_PORT_DEFAULT:-15432}}}" \
+  MINIO_PORT="${MINIO_PORT:-${AGENT_MINIO_PORT:-${HARNESS_MINIO_PORT_DEFAULT:-19000}}}" \
+  BROWSER_PORT="${BROWSER_PORT:-${AGENT_BROWSER_PORT:-${HARNESS_BROWSER_PORT_DEFAULT:-13001}}}" \
+  REPO_ROOT="$work_dir" \
+    envsubst '${AGENT_ID} ${API_PORT} ${FE_PORT} ${DEBUG_PORT} ${DB_PORT} ${MINIO_PORT} ${BROWSER_PORT} ${REPO_ROOT}' \
+    < "$template" > "$env_file"
+}
+
+# har_launch_preflight <agent_id> <force> <replace> [resume]
+# Exit 0 when ready; 2 when occupied/replace required; 1 on machine blockers.
+# Sets FE_PORT/API_PORT/DEBUG_PORT when this harness uses PM2.
+har_launch_preflight() {
+  local agent_id="$1"
+  local force="${2:-false}"
+  local replace="${3:-false}"
+  local resume="${4:-false}"
+
+  if [ "$resume" = true ]; then
+    if ! slot_is_resumable "$agent_id"; then
+      local status
+      status="$(slot_session_status "$agent_id")"
+      echo "ERROR: slot ${agent_id} is not resumable (status=${status:-none}; need failed or starting)." >&2
+      echo "  Use a normal launch, or --replace to start a fresh session." >&2
+      return 2
+    fi
+    echo "==> [agent-${agent_id}] Resuming partial launch (worktree and deps preserved)..." >&2
+  elif slot_is_occupied "$agent_id"; then
+    if [ "$replace" != true ] && [ "${HAR_CONFIRM_REPLACE:-}" != "1" ]; then
+      print_slot_replace_warning "$agent_id"
+      echo "ERROR: slot ${agent_id} is occupied — pass --replace to proceed." >&2
+      return 2
+    fi
+    local wt
+    wt="$(existing_slot_worktree "$agent_id")"
+    if [ -n "$wt" ] && slot_worktree_dirty "$wt" && [ "$force" != true ]; then
+      echo "ERROR: dirty worktree requires --force after explicit user approval." >&2
+      return 2
+    fi
+  fi
+
+  if har_harness_uses_pm2; then
+    har_check_foreign_pm2 "$agent_id" || return 1
+    har_allocate_slot_app_ports "$agent_id" || return 1
+    har_warn_control_on_default_port "$agent_id"
+    local port occupant
+    for port in $(printf '%s\n' "$FE_PORT" "$API_PORT" | sort -u); do
+      har_check_control_port_conflict "$port" || return 1
+      occupant="$(har_port_docker_occupant "$port")"
+      if [ -n "$occupant" ] && [[ "$occupant" != har-${HARNESS_PROJECT_NAME}-* ]]; then
+        echo "ERROR: Docker container \"${occupant}\" binds port ${port}." >&2
+        echo "  Stop it with: docker stop ${occupant}" >&2
+        return 1
+      fi
+    done
+  fi
+  return 0
+}
+
+# Load persisted app/infra ports from .env.agent.<id> or the slot registry.
+load_agent_ports() {
+  local agent_id="$1"
+  local repo_root="$2"
+  local env_file reg ports_json
+  env_file="$(resolve_agent_env_file "$agent_id" "$repo_root" 2>/dev/null || true)"
+  if [ -n "$env_file" ] && [ -f "$env_file" ]; then
+    # shellcheck source=/dev/null
+    source "$env_file"
+    FE_PORT="${FE_PORT:-}"
+    API_PORT="${API_PORT:-${PORT:-}}"
+    DEBUG_PORT="${DEBUG_PORT:-}"
+    DB_PORT="${PGPORT:-${DB_PORT:-}}"
+    return 0
+  fi
+  reg="$(slot_registry_file "$agent_id")"
+  if [ -f "$reg" ]; then
+    ports_json="$(node -e '
+try {
+  const p = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).ports;
+  if (p) process.stdout.write(JSON.stringify(p));
+} catch {}
+' "$reg" 2>/dev/null || true)"
+    if [ -n "$ports_json" ]; then
+      FE_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.frontend??''))" "$ports_json")"
+      API_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.api??''))" "$ports_json")"
+      DEBUG_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.debug??''))" "$ports_json")"
+      DB_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.db??''))" "$ports_json")"
+      export FE_PORT API_PORT DEBUG_PORT DB_PORT
+      return 0
+    fi
+  fi
+  har_allocate_slot_app_ports "$agent_id"
+  DB_PORT="${AGENT_DB_PORT:-${HARNESS_DB_PORT_DEFAULT:-15432}}"
+  export FE_PORT API_PORT DEBUG_PORT DB_PORT
+}
+
+# ── Project-scoped PM2 names ────────────────────────────────────────────────────
+# Pattern: har-<project>-agent-<id>-<service> (machine-global PM2 namespace).
+
+har_pm2_slot_prefix() {
+  echo "har-${HARNESS_PROJECT_NAME}-agent-${1}"
+}
+
+har_pm2_delete_regex() {
+  echo "/^har-${HARNESS_PROJECT_NAME}-agent-${1}-/"
+}
+
+har_tmux_session() {
+  echo "har-${HARNESS_PROJECT_NAME}-agent-${1}"
+}
+
 # ── 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

package/dist/templates/har-boilerplate/attach.sh

@@ -4,8 +4,14 @@
 # Usage: ./.har/attach.sh <agent-id>
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
 AGENT_ID="${1:?Usage: attach.sh <agent-id>}"
-SESSION="agent-${AGENT_ID}"
+SESSION="$(har_tmux_session "$AGENT_ID")"
 
 if ! tmux has-session -t "$SESSION" 2>/dev/null; then
   echo "No tmux session found: $SESSION" >&2

package/dist/templates/har-boilerplate/ecosystem.agent.template.cjs

@@ -26,7 +26,7 @@ module.exports = {
     // Example Node dev process. Replace with this repo's actual primary app
     // command (Rails, Django, Go, Java, etc. should not keep this npm entry).
     {
-      name: 'agent-${AGENT_ID}-api',
+      name: 'har-${HARNESS_PROJECT_NAME}-agent-${AGENT_ID}-api',
       script: 'npm',
       args: 'run dev',
       interpreter: 'none',

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

@@ -2,7 +2,7 @@
 # DO NOT EDIT — regenerated on every launch
 AGENT_ID=${AGENT_ID}
 
-# Ports (formula: BASE + AGENT_ID * 10)
+# Ports (allocated at launch — may differ from BASE + AGENT_ID × STEP when busy)
 PORT=${API_PORT}
 FE_PORT=${FE_PORT}
 API_PORT=${API_PORT}

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

@@ -11,10 +11,37 @@ export HARNESS_USE_WORKTREE=true
 export HARNESS_PRIMARY_APP=app
 
 export HARNESS_TEMPLATE_DB=template___PROJECT_NAME__
+
+# ── Per-slot app ports (PM2 / primary app) ────────────────────────────────────
+# Defaults: BASE + (AGENT_ID × HARNESS_PORT_STEP). launch.sh scans the slot lane
+# when busy and writes resolved FE_PORT / API_PORT / DEBUG_PORT to .env.agent.<id>.
 export HARNESS_FE_BASE_PORT=3000
 export HARNESS_API_BASE_PORT=8000
+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.
+# 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
+
 # Agent slot limits — set based on what your machine can run in parallel
 export HARNESS_AGENT_SLOT_MIN=1
 export HARNESS_AGENT_SLOT_MAX=5