fix(showcase): rewrite --isolate to use temp overlays + slot-based port allocation (CopilotKit#4570)

jpr5 · web-flow · commit bbf1cf37b575 · 2026-05-01T00:14:09.000-07:00
## Summary
- Never mutate originals -- temp overlay in $TMPDIR instead of in-place
.iso-bak
- Slot-based port allocation via atomic mkdir for parallel support (slot
0 = +200, slot 1 = +400, etc.)
- --project-name scoping prevents Docker container/network collisions
- Stale slot cleanup via PID check + 2-hour age fallback
- LOCAL_PORTS_FILE env var for TS harness to read offset ports

## Test plan
- [ ] Originals untouched after isolated run (md5 verified)
- [ ] CI green
- [ ] Two parallel --isolate runs don't conflict
diff --git a/showcase/harness/src/cli/config.ts b/showcase/harness/src/cli/config.ts
@@ -20,7 +20,11 @@ export interface LocalConfig {
 }
 
 export function loadConfig(): LocalConfig {
-  const portsFile = path.join(SHOWCASE_DIR, "shared/local-ports.json");
+  // Honor LOCAL_PORTS_FILE env var (set by isolation overlay) so the harness
+  // reads offset ports from a temp file instead of the checked-in original.
+  const portsFile =
+    process.env.LOCAL_PORTS_FILE ||
+    path.join(SHOWCASE_DIR, "shared/local-ports.json");
   const localPorts = JSON.parse(fs.readFileSync(portsFile, "utf-8")) as Record<
     string,
     number
diff --git a/showcase/harness/src/cli/doctor.ts b/showcase/harness/src/cli/doctor.ts
@@ -10,7 +10,9 @@ const log = createLogger({ component: "doctor" });
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SHOWCASE_DIR = path.resolve(__dirname, "../../..");
 const COMPOSE_FILE = path.join(SHOWCASE_DIR, "docker-compose.local.yml");
-const PORTS_FILE = path.join(SHOWCASE_DIR, "shared/local-ports.json");
+const PORTS_FILE =
+  process.env.LOCAL_PORTS_FILE ||
+  path.join(SHOWCASE_DIR, "shared/local-ports.json");
 
 /** Well-known infra service ports. */
 const INFRA_PORTS: Record<string, number> = {
diff --git a/showcase/harness/src/cli/lifecycle.ts b/showcase/harness/src/cli/lifecycle.ts
@@ -18,7 +18,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SHOWCASE_DIR = path.resolve(__dirname, "../../..");
 const COMPOSE_FILE = path.join(SHOWCASE_DIR, "docker-compose.local.yml");
 const INTEGRATIONS_DIR = path.join(SHOWCASE_DIR, "integrations");
-const PORTS_FILE = path.join(SHOWCASE_DIR, "shared/local-ports.json");
+// Honor LOCAL_PORTS_FILE env var (set by isolation overlay) so the harness
+// reads offset ports from a temp file instead of the checked-in original.
+const PORTS_FILE =
+  process.env.LOCAL_PORTS_FILE ||
+  path.join(SHOWCASE_DIR, "shared/local-ports.json");
 
 /** Well-known infra service ports that aren't in local-ports.json. */
 const INFRA_PORTS: Record<string, number> = {
diff --git a/showcase/scripts/cli/_common.sh b/showcase/scripts/cli/_common.sh
@@ -111,31 +111,116 @@ wait_healthy() {
 # ── Isolation helpers ───────────────────────────────────────────────────────
 
 ISOLATE_NAME=""
-ISOLATE_PORT_OFFSET=200
+ISOLATE_PORT_OFFSET=0
+ISOLATE_SLOT=""
 ISOLATE_ACTIVE=false
+ISOLATE_TMPDIR=""
+
+ISOLATE_SLOT_DIR="/tmp/showcase-isolate-slots"
+ISOLATE_STALE_THRESHOLD=7200  # 2 hours in seconds
+
+# Claim an isolation slot using atomic mkdir. Slots start at 0 and increment.
+# Each slot dir contains a "pid" file for stale-detection. The port offset is
+# (slot + 1) * 200, so slot 0 → +200, slot 1 → +400, etc.
+_claim_isolate_slot() {
+  mkdir -p "$ISOLATE_SLOT_DIR"
+
+  # Clean up stale slots first (crashed runs older than 2 hours, or dead PIDs)
+  local slot_entry
+  for slot_entry in "$ISOLATE_SLOT_DIR"/[0-9]*; do
+    [ -d "$slot_entry" ] || continue
+    local slot_pid_file="$slot_entry/pid"
+    if [ -f "$slot_pid_file" ]; then
+      local slot_pid
+      slot_pid="$(cat "$slot_pid_file" 2>/dev/null)"
+      # If the PID is dead, remove the stale slot
+      if [ -n "$slot_pid" ] && ! kill -0 "$slot_pid" 2>/dev/null; then
+        info "Reclaiming stale slot $(basename "$slot_entry") (PID $slot_pid dead)"
+        rm -rf "$slot_entry"
+        continue
+      fi
+    fi
+    # Fallback: age-based cleanup if no pid file or pid check inconclusive
+    if [ ! -f "$slot_pid_file" ]; then
+      local slot_age
+      if [[ "$OSTYPE" == darwin* ]]; then
+        slot_age=$(( $(date +%s) - $(stat -f %m "$slot_entry") ))
+      else
+        slot_age=$(( $(date +%s) - $(stat -c %Y "$slot_entry") ))
+      fi
+      if [ "$slot_age" -gt "$ISOLATE_STALE_THRESHOLD" ]; then
+        info "Reclaiming stale slot $(basename "$slot_entry") (age ${slot_age}s > ${ISOLATE_STALE_THRESHOLD}s)"
+        rm -rf "$slot_entry"
+      fi
+    fi
+  done
+
+  # Claim the first available slot (mkdir is atomic — if it succeeds, we own it)
+  local n=0
+  while true; do
+    if mkdir "$ISOLATE_SLOT_DIR/$n" 2>/dev/null; then
+      ISOLATE_SLOT="$n"
+      echo "$$" > "$ISOLATE_SLOT_DIR/$n/pid"
+      ISOLATE_PORT_OFFSET=$(( (n + 1) * 200 ))
+      return 0
+    fi
+    n=$((n + 1))
+    if [ "$n" -gt 45 ]; then
+      die "No isolation slots available (0-45 exhausted). Check /tmp/showcase-isolate-slots/"
+    fi
+  done
+}
+
+# Release the claimed isolation slot
+_release_isolate_slot() {
+  if [ -n "$ISOLATE_SLOT" ] && [ -d "$ISOLATE_SLOT_DIR/$ISOLATE_SLOT" ]; then
+    rm -rf "$ISOLATE_SLOT_DIR/$ISOLATE_SLOT"
+  fi
+  # Remove the parent dir if now empty
+  rmdir "$ISOLATE_SLOT_DIR" 2>/dev/null || true
+  ISOLATE_SLOT=""
+}
 
 apply_isolation() {
-  local name="${1:-isolate-$$}"
-  ISOLATE_NAME="$name"
+  local name="${1:-}"
   ISOLATE_ACTIVE=true
+
+  # Guard: clean up stale .iso-bak files from a prior botched run that
+  # mutated originals in-place (the old approach). This makes migration safe.
+  if [ -f "${PORTS_FILE}.iso-bak" ] || [ -f "${COMPOSE_FILE}.iso-bak" ]; then
+    warn "Stale .iso-bak files found from a prior crash — restoring originals"
+    [ -f "${PORTS_FILE}.iso-bak" ] && mv "${PORTS_FILE}.iso-bak" "$PORTS_FILE"
+    [ -f "${COMPOSE_FILE}.iso-bak" ] && mv "${COMPOSE_FILE}.iso-bak" "$COMPOSE_FILE"
+  fi
+
+  # Claim a slot for unique port offsets
+  _claim_isolate_slot
+
+  # Build the isolation name, incorporating the slot for uniqueness
+  if [ -z "$name" ]; then
+    name="showcase-iso${ISOLATE_SLOT}"
+  fi
+  ISOLATE_NAME="$name"
   export COMPOSE_PROJECT_NAME="$name"
 
-  # Backup originals
-  cp "$PORTS_FILE" "${PORTS_FILE}.iso-bak"
-  cp "$COMPOSE_FILE" "${COMPOSE_FILE}.iso-bak"
+  # Create temp directory for overlay copies (originals stay untouched)
+  ISOLATE_TMPDIR="${TMPDIR:-/tmp}/showcase-isolate-$$"
+  mkdir -p "$ISOLATE_TMPDIR"
 
-  # Offset ports in local-ports.json
+  # Generate offset ports file in the temp dir
+  local tmp_ports="$ISOLATE_TMPDIR/local-ports.json"
   python3 -c "
-import json
+import json, sys
 with open('$PORTS_FILE') as f:
     ports = json.load(f)
 offset = {k: v + $ISOLATE_PORT_OFFSET for k, v in ports.items()}
-with open('$PORTS_FILE', 'w') as f:
+with open('$tmp_ports', 'w') as f:
     json.dump(offset, f, indent=2)
     f.write('\n')
 "
 
-  # Offset host ports and container names in docker-compose.local.yml
+  # Generate offset compose file in the temp dir
+  local tmp_compose="$ISOLATE_TMPDIR/docker-compose.local.yml"
   python3 -c "
 import re
 with open('$COMPOSE_FILE') as f:
@@ -150,22 +235,35 @@ def offset_port(m):
 content = re.sub(r'(\s+)- \"(\d+):(\d+)\"', offset_port, content)
 content = content.replace('container_name: showcase-', 'container_name: $name-')
 
-with open('$COMPOSE_FILE', 'w') as f:
+with open('$tmp_compose', 'w') as f:
     f.write(content)
 "
 
+  # Override shell variables so all downstream code uses the temp files.
+  # Originals are NEVER mutated.
+  COMPOSE_FILE="$tmp_compose"
+  COMPOSE_CMD="docker compose -f $COMPOSE_FILE --project-name $name"
+  PORTS_FILE="$tmp_ports"
+
+  # Export for the TS harness CLI (config.ts / lifecycle.ts honor this)
+  export LOCAL_PORTS_FILE="$tmp_ports"
+
   # Idempotent: tear down any prior run with this name
   $COMPOSE_CMD down --remove-orphans 2>/dev/null || true
 
-  info "Isolation active: project=$name ports=+$ISOLATE_PORT_OFFSET"
+  info "Isolation active: project=$name slot=$ISOLATE_SLOT ports=+$ISOLATE_PORT_OFFSET tmpdir=$ISOLATE_TMPDIR"
 }
 
 restore_isolation() {
   if $ISOLATE_ACTIVE; then
-    info "Tearing down isolated group: $ISOLATE_NAME"
+    info "Tearing down isolated group: $ISOLATE_NAME (slot $ISOLATE_SLOT)"
     $COMPOSE_CMD down --remove-orphans 2>/dev/null || true
-    [ -f "${PORTS_FILE}.iso-bak" ] && mv "${PORTS_FILE}.iso-bak" "$PORTS_FILE"
-    [ -f "${COMPOSE_FILE}.iso-bak" ] && mv "${COMPOSE_FILE}.iso-bak" "$COMPOSE_FILE"
+    # Just remove the temp dir — originals were never touched
+    if [ -n "$ISOLATE_TMPDIR" ] && [ -d "$ISOLATE_TMPDIR" ]; then
+      rm -rf "$ISOLATE_TMPDIR"
+    fi
+    # Release the isolation slot so other runs can claim it
+    _release_isolate_slot
     ISOLATE_ACTIVE=false
   fi
 }
diff --git a/showcase/scripts/cli/cmd-test.sh b/showcase/scripts/cli/cmd-test.sh
@@ -101,10 +101,12 @@ cmd_test() {
 
   need_slug "$slug"
 
-  # Apply isolation if requested (must happen before any compose commands)
+  # Apply isolation if requested (must happen before any compose commands).
+  # Register the trap BEFORE apply_isolation so cleanup runs even if the
+  # function itself crashes partway through.
   if $use_isolate; then
-    apply_isolation "${isolate_name:-}"
     trap restore_isolation EXIT
+    apply_isolation "${isolate_name:-}"
   fi
 
   # Build the filter description for the info line
