@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/sales-agentforce-pipeline-management-configure/scripts/shared/agent-bundle-publish.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# Shared library for Sales Agent authoring bundle publish and activation
+#
+# Functions:
+#   publish_and_activate_agent <org-alias> <on-error-behavior> [output-style]
+#
+# Parameters:
+#   org-alias: Salesforce org alias
+#   on-error-behavior: "exit" (hard fail on error) or "return" (return non-zero)
+#   output-style: "plain" (default, plain echo) or "structured" (log_pass/log_info style)
+#
+# Returns:
+#   0 on success
+#   1 on failure
+#
+# Environment:
+#   SCRIPT_DIR must be set (parent script's directory)
+
+# Source agent-detection helpers (pm_bot_latest_version, etc.)
+# Use a local resolution that doesn't depend on the caller's SCRIPT_DIR.
+# shellcheck source=./agent-detection.sh
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/agent-detection.sh"
+
+publish_and_activate_agent() {
+  local ORG_ALIAS="$1"
+  local ON_ERROR="${2:-exit}"
+  local OUTPUT_STYLE="${3:-plain}"
+
+  # Clear exported state from any prior call to prevent stale values on failure
+  unset AGENT_VERSION
+  unset AGENT_API_NAME
+
+  local AGENT_BUNDLE="$SCRIPT_DIR/../assets/sales_management_agent.agent"
+  local BUNDLE_META="$SCRIPT_DIR/../assets/sales_management_agent.bundle-meta.xml"
+
+  # Output helper functions based on style
+  local msg_header msg_pass msg_error msg_info
+  if [[ "$OUTPUT_STYLE" == "structured" ]]; then
+    msg_header() { log_info "$1"; }
+    msg_pass() { log_pass "$1"; }
+    msg_error() { echo "  ERROR: $1"; }
+    msg_info() { echo "    $1"; }
+  else
+    msg_header() { echo "=== $1 ==="; }
+    msg_pass() { echo "  ✓ $1"; }
+    msg_error() { echo "  ERROR: $1"; }
+    msg_info() { echo "  $1"; }
+  fi
+
+  # Check for bundle assets
+  if [[ ! -f "$AGENT_BUNDLE" || ! -f "$BUNDLE_META" ]]; then
+    msg_error "Agent bundle assets not found at: $AGENT_BUNDLE"
+    if [[ "$ON_ERROR" == "exit" ]]; then
+      echo ""
+      echo "SETUP FAILED: A Pipeline Management BotDefinition is REQUIRED for user interaction."
+      exit 1
+    fi
+    return 1
+  fi
+
+  msg_header "Creating Sales Agent via authoring bundle"
+
+  # Create temp directory for bundle deployment
+  local TEMP_DIR
+  TEMP_DIR=$(mktemp -d -t sales-agent-bundle.XXXXXX)
+  # Use EXIT trap so it fires even on explicit exit calls
+  trap 'rm -rf "$TEMP_DIR"' EXIT
+
+  # Create sfdx-project.json in temp dir
+  cat > "$TEMP_DIR/sfdx-project.json" << 'SFDX'
+{"packageDirectories": [{"path": "force-app", "default": true}], "sourceApiVersion": "67.0"}
+SFDX
+
+  # Copy authoring bundle to temp deployment directory
+  mkdir -p "$TEMP_DIR/force-app/main/default/aiAuthoringBundles/SalesAgent"
+  if ! cp "$AGENT_BUNDLE" "$TEMP_DIR/force-app/main/default/aiAuthoringBundles/SalesAgent/SalesAgent.agent"; then
+    msg_error "Failed to stage bundle agent file"
+    rm -rf "$TEMP_DIR"
+    trap - EXIT
+    if [[ "$ON_ERROR" == "exit" ]]; then
+      echo ""
+      echo "SETUP FAILED: A Pipeline Management BotDefinition is REQUIRED for user interaction."
+      exit 1
+    fi
+    return 1
+  fi
+  if ! cp "$BUNDLE_META" "$TEMP_DIR/force-app/main/default/aiAuthoringBundles/SalesAgent/SalesAgent.bundle-meta.xml"; then
+    msg_error "Failed to stage bundle metadata file"
+    rm -rf "$TEMP_DIR"
+    trap - EXIT
+    if [[ "$ON_ERROR" == "exit" ]]; then
+      echo ""
+      echo "SETUP FAILED: A Pipeline Management BotDefinition is REQUIRED for user interaction."
+      exit 1
+    fi
+    return 1
+  fi
+
+  # Publish authoring bundle from temp directory
+  msg_info "Publishing Sales Agent authoring bundle..."
+  local PUBLISH_RESULT
+  PUBLISH_RESULT=$(cd "$TEMP_DIR" && sf agent publish authoring-bundle --json --api-name SalesAgent --target-org "$ORG_ALIAS" 2>/dev/null || echo '{"status":1}')
+
+  if ! echo "$PUBLISH_RESULT" | jq -e '.status == 0' >/dev/null 2>&1; then
+    local PUBLISH_ERR
+    PUBLISH_ERR=$(echo "$PUBLISH_RESULT" | jq -r '.message // .result.message // .result.errors[0].message // "unknown"' 2>/dev/null || echo "unknown")
+    msg_error "Authoring bundle publish failed: $PUBLISH_ERR"
+    rm -rf "$TEMP_DIR"
+    trap - EXIT
+    if [[ "$ON_ERROR" == "exit" ]]; then
+      echo ""
+      echo "SETUP FAILED: A Pipeline Management BotDefinition is REQUIRED for user interaction."
+      exit 1
+    fi
+    return 1
+  fi
+
+  msg_pass "Sales Agent published successfully"
+
+  # Query for the latest BotVersion with retry (async provisioning).
+  # Match the bot by AgentTemplate (the same field the scheduled flow uses),
+  # not by hardcoded DeveloperName — the bundle may publish under a different
+  # local name in some orgs.
+  msg_info "Querying for latest version..."
+  local LATEST_VERSION=""
+  for attempt in {1..3}; do
+    LATEST_VERSION=$(pm_bot_latest_version "$ORG_ALIAS")
+
+    if [[ -n "$LATEST_VERSION" ]]; then
+      break
+    fi
+
+    if [[ $attempt -lt 3 ]]; then
+      echo "    Version not yet available, retrying in 5s... (attempt $attempt/3)"
+      sleep 5
+    fi
+  done
+
+  if [[ -z "$LATEST_VERSION" ]]; then
+    msg_error "Could not query BotVersion after publish. BotDefinition may still be provisioning. Wait 30s and check Setup → Agents."
+    rm -rf "$TEMP_DIR"
+    trap - EXIT
+    if [[ "$ON_ERROR" == "exit" ]]; then
+      echo ""
+      echo "SETUP FAILED: A Pipeline Management BotDefinition is REQUIRED for user interaction."
+      exit 1
+    fi
+    return 1
+  fi
+
+  # Resolve the actual published DeveloperName from AgentTemplate so we
+  # activate whatever name the bundle landed under (defaults to "SalesAgent"
+  # but the org may already have an upgraded NGA bot with a different name).
+  AGENT_API_NAME=$(pm_bot_developer_name "$ORG_ALIAS")
+  if [[ -z "$AGENT_API_NAME" ]]; then
+    AGENT_API_NAME="SalesAgent"
+  fi
+
+  # Activate the agent with dynamic version
+  msg_info "Activating $AGENT_API_NAME version $LATEST_VERSION..."
+  local ACTIVATE_RESULT
+  ACTIVATE_RESULT=$(sf agent activate --api-name "$AGENT_API_NAME" --version "$LATEST_VERSION" --target-org "$ORG_ALIAS" --json 2>/dev/null || echo '{"status":1}')
+
+  if ! echo "$ACTIVATE_RESULT" | jq -e '.status == 0' >/dev/null 2>&1; then
+    local ACTIVATE_ERR
+    ACTIVATE_ERR=$(echo "$ACTIVATE_RESULT" | jq -r '.message // .result.message // .result.errors[0].message // "unknown"' 2>/dev/null || echo "unknown")
+    msg_error "Agent activation failed: $ACTIVATE_ERR. The agent was published but activation failed."
+    rm -rf "$TEMP_DIR"
+    trap - EXIT
+    if [[ "$ON_ERROR" == "exit" ]]; then
+      echo ""
+      echo "SETUP FAILED: A Pipeline Management BotDefinition is REQUIRED for user interaction."
+      exit 1
+    fi
+    return 1
+  fi
+
+  msg_pass "$AGENT_API_NAME activated successfully (version $LATEST_VERSION)"
+
+  # Export version and resolved api-name for caller to use
+  export AGENT_VERSION="$LATEST_VERSION"
+  export AGENT_API_NAME
+
+  # Clean up temp directory before returning (EXIT trap only fires on exit, not return)
+  rm -rf "$TEMP_DIR"
+  trap - EXIT  # Remove the trap since we've already cleaned up
+
+  return 0
+}

package/skills/sales-agentforce-pipeline-management-configure/scripts/shared/agent-detection.sh

@@ -0,0 +1,239 @@
+#!/bin/bash
+# Shared library for Pipeline Management agent detection.
+#
+# The Pipeline Management scheduled flow (sales_pipe_mgmt__OppSuggGenSchFlow)
+# finds the Sales Agent bot by querying BotDefinition.AgentTemplate, NOT by
+# a hardcoded DeveloperName. Setup/verify scripts must match the same logic
+# so they detect the agent regardless of what local name (SalesAgent,
+# Sale_Agent, etc.) it was published with.
+#
+# The product currently supports two agent templates:
+#   - SalesMgmt__SalesAgent      (legacy)
+#   - SalesMgmt__NGASalesAgent   (upgraded NGA, used by our authoring bundle)
+#
+# Both flows (Test.flow, Process_Field_Update_Suggestions.flow) check
+# AgentTemplate. We do the same here.
+
+# Comma-separated AgentTemplate API names that identify a Pipeline Management
+# Sales Agent. Quoted for SOQL IN(...) usage.
+PM_AGENT_TEMPLATES_SOQL="'SalesMgmt__NGASalesAgent','SalesMgmt__SalesAgent'"
+
+# Activation state lives on BotVersion.Status (Active|Inactive), not on
+# BotDefinition (which only has IsDeleted).
+#
+# DEPRECATED: This correlated subquery hangs 60+ seconds on some orgs and must
+# NOT be embedded in detection queries (removed in de77d520). Retained only so
+# any lingering external caller still resolves the symbol; callers that need to
+# know whether a bot is active should run a SEPARATE flat query on BotVersion
+# (e.g. SELECT COUNT() FROM BotVersion WHERE BotDefinitionId='...' AND
+# Status='Active') instead of splicing this into a BotDefinition WHERE clause.
+PM_ACTIVE_BOT_FILTER="Id IN (SELECT BotDefinitionId FROM BotVersion WHERE Status = 'Active')"
+
+# Print the DeveloperName of the Pipeline Management BotDefinition (if any),
+# detected by AgentTemplate. Empty string when not found.
+#
+# NOTE: Does NOT filter by Active status to avoid slow/hanging subqueries.
+# Callers should verify Active status separately if needed.
+#
+# Usage: name=$(pm_bot_developer_name "$ORG_ALIAS")
+pm_bot_developer_name() {
+  local org_alias="$1"
+  sf data query \
+    --query "SELECT DeveloperName FROM BotDefinition WHERE AgentTemplate IN (${PM_AGENT_TEMPLATES_SOQL}) ORDER BY LastModifiedDate DESC LIMIT 1" \
+    --target-org "$org_alias" \
+    --json 2>/dev/null \
+    | jq -r '.result.records[0].DeveloperName // empty' 2>/dev/null \
+    || echo ""
+}
+
+# Print the total number of Pipeline Management bots (BotDefinition rows
+# matching PM AgentTemplate). Returns 0 if none, on error, or if the result
+# can't be parsed.
+#
+# NOTE: Does NOT filter by Active status to avoid slow/hanging subqueries.
+#
+# Usage: count=$(pm_bot_count "$ORG_ALIAS")
+pm_bot_count() {
+  local org_alias="$1"
+  local count
+  count=$(sf data query \
+    --query "SELECT Id FROM BotDefinition WHERE AgentTemplate IN (${PM_AGENT_TEMPLATES_SOQL})" \
+    --target-org "$org_alias" \
+    --json 2>/dev/null \
+    | jq -r '.result.totalSize // 0' 2>/dev/null \
+    | head -1 | tr -cd '0-9')
+  echo "${count:-0}"
+}
+
+# Print the AgentTemplate API name of the active Pipeline Management bot.
+# Used to keep the deployed flow's SalesManagementAgentTemplate constant
+# in sync with the actual bot on the org (legacy SalesMgmt__SalesAgent vs
+# upgraded SalesMgmt__NGASalesAgent), so the flow's BotDefinition lookup
+# will match at runtime.
+#
+# Selection rule when both templates have a bot: prefer NGA (the forward
+# direction; our authoring bundle publishes NGA). SOQL does not support CASE
+# in ORDER BY, so we query NGA first and fall back to legacy.
+#
+# NOTE: Does NOT filter by Active status to avoid slow/hanging subqueries.
+# Callers should verify Active status separately if needed.
+#
+# Exit codes distinguish failure modes for callers:
+#   0 + stdout populated  -> bot found, prints template name
+#   1 + empty stdout      -> no PM bot exists on the org
+#   2 + empty stdout      -> SOQL/auth/network failure (transient)
+#
+# Usage:
+#   if tpl=$(pm_bot_agent_template "$ORG_ALIAS"); then ... fi
+#   rc=$?  # 0=ok, 1=no-bot, 2=query-failed
+pm_bot_agent_template() {
+  local org_alias="$1"
+  local raw rc tpl
+
+  raw=$(sf data query \
+    --query "SELECT AgentTemplate FROM BotDefinition WHERE AgentTemplate = 'SalesMgmt__NGASalesAgent' ORDER BY LastModifiedDate DESC LIMIT 1" \
+    --target-org "$org_alias" \
+    --json 2>/dev/null)
+  rc=$?
+  if [[ $rc -ne 0 || -z "$raw" ]]; then
+    return 2
+  fi
+  tpl=$(echo "$raw" | jq -r '.result.records[0].AgentTemplate // empty' 2>/dev/null)
+  if [[ -n "$tpl" ]]; then
+    echo "$tpl"
+    return 0
+  fi
+
+  raw=$(sf data query \
+    --query "SELECT AgentTemplate FROM BotDefinition WHERE AgentTemplate = 'SalesMgmt__SalesAgent' ORDER BY LastModifiedDate DESC LIMIT 1" \
+    --target-org "$org_alias" \
+    --json 2>/dev/null)
+  rc=$?
+  if [[ $rc -ne 0 || -z "$raw" ]]; then
+    return 2
+  fi
+  tpl=$(echo "$raw" | jq -r '.result.records[0].AgentTemplate // empty' 2>/dev/null)
+  if [[ -n "$tpl" ]]; then
+    echo "$tpl"
+    return 0
+  fi
+  return 1
+}
+
+# Print the number of agent users that HOLD SalesManagementAgentUserPsg.
+# This — not PSG existence — is a real "PM setup has run" signal, because the
+# two PM PSGs (SalesManagementUserPsg / SalesManagementAgentUserPsg) ship with
+# the Agentforce-for-Sales license and exist even in a never-configured org.
+# Returns 0 if none / on error.
+#
+# Usage: n=$(pm_agent_user_holds_psg "$ORG_ALIAS")
+pm_agent_user_holds_psg() {
+  local org_alias="$1" count
+  count=$(sf data query \
+    --query "SELECT Id FROM PermissionSetAssignment WHERE Assignee.Username LIKE '%salesmanagementagentuser%' AND PermissionSetGroup.DeveloperName='SalesManagementAgentUserPsg'" \
+    --target-org "$org_alias" --json 2>/dev/null \
+    | jq -r '.result.totalSize // 0' 2>/dev/null | head -1 | tr -cd '0-9')
+  echo "${count:-0}"
+}
+
+# Print the number of scheduled flows cloned from the PM template
+# (sales_pipe_mgmt__OppSuggGenSchFlow). A real "PM setup has run" signal.
+# Returns 0 if none / on error.
+#
+# Usage: n=$(pm_flow_clone_exists "$ORG_ALIAS")
+pm_flow_clone_exists() {
+  local org_alias="$1" count
+  count=$(sf data query \
+    --query "SELECT Id FROM FlowDefinitionView WHERE SourceTemplateId='sales_pipe_mgmt__OppSuggGenSchFlow' AND IsTemplate=false" \
+    --target-org "$org_alias" --json 2>/dev/null \
+    | jq -r '.result.totalSize // 0' 2>/dev/null | head -1 | tr -cd '0-9')
+  echo "${count:-0}"
+}
+
+# Print the latest BotVersion VersionNumber for the PM bot (any status). Empty
+# if no version exists. Note: This returns the most recent version regardless
+# of activation status, which is necessary for the publish-then-activate flow
+# where the freshly published version is still Inactive.
+#
+# Usage: ver=$(pm_bot_latest_version "$ORG_ALIAS")
+pm_bot_latest_version() {
+  local org_alias="$1"
+  sf data query \
+    --query "SELECT VersionNumber FROM BotVersion WHERE BotDefinition.AgentTemplate IN (${PM_AGENT_TEMPLATES_SOQL}) ORDER BY VersionNumber DESC LIMIT 1" \
+    --target-org "$org_alias" \
+    --json 2>/dev/null \
+    | jq -r '.result.records[0].VersionNumber // empty' 2>/dev/null \
+    || echo ""
+}
+
+# Print the number of ACTIVE BotVersions for the PM bot. A bot can exist
+# (BotDefinition present) yet have no active version — this is exactly the
+# state auto-provisioning leaves the bot in: the BotVersion lands Inactive and
+# must be activated before the scheduled flow will add the agent user to
+# opportunity teams or Agent Access can be defined. Uses a SEPARATE flat query
+# on BotVersion (never a correlated subquery — see PM_ACTIVE_BOT_FILTER note).
+# Returns 0 if none / on error.
+#
+# Usage: n=$(pm_bot_active_version_count "$ORG_ALIAS")
+pm_bot_active_version_count() {
+  local org_alias="$1" count
+  count=$(sf data query \
+    --query "SELECT Id FROM BotVersion WHERE BotDefinition.AgentTemplate IN (${PM_AGENT_TEMPLATES_SOQL}) AND Status = 'Active'" \
+    --target-org "$org_alias" \
+    --json 2>/dev/null \
+    | jq -r '.result.totalSize // 0' 2>/dev/null | head -1 | tr -cd '0-9')
+  echo "${count:-0}"
+}
+
+# Ensure the PM bot has an ACTIVE BotVersion, activating the latest version if
+# not. Idempotent: a no-op (returns 0) when an active version already exists.
+# Uses `sf agent activate`, matching the activation path in
+# publish_and_activate_agent. Prints progress via plain echo.
+#
+# Returns:
+#   0 - an active version exists (already, or after successful activation)
+#   1 - activation was attempted but failed, or no version exists to activate
+#
+# Usage: activate_pm_bot_if_inactive "$ORG_ALIAS"
+activate_pm_bot_if_inactive() {
+  local org_alias="$1"
+
+  local active_count
+  active_count=$(pm_bot_active_version_count "$org_alias")
+  if [[ "$active_count" -ge 1 ]]; then
+    return 0
+  fi
+
+  local latest_version api_name
+  latest_version=$(pm_bot_latest_version "$org_alias")
+  if [[ -z "$latest_version" ]]; then
+    echo "  ERROR: BotDefinition exists but has no BotVersion to activate."
+    return 1
+  fi
+
+  api_name=$(pm_bot_developer_name "$org_alias")
+  [[ -z "$api_name" ]] && api_name="SalesAgent"
+
+  echo "  Activating $api_name version $latest_version (auto-provisioned version was Inactive)..."
+  local activate_result
+  activate_result=$(sf agent activate --api-name "$api_name" --version "$latest_version" --target-org "$org_alias" --json 2>/dev/null || echo '{"status":1}')
+
+  if ! echo "$activate_result" | jq -e '.status == 0' >/dev/null 2>&1; then
+    local activate_err
+    activate_err=$(echo "$activate_result" | jq -r '.message // .result.message // .result.errors[0].message // "unknown"' 2>/dev/null || echo "unknown")
+    echo "  ERROR: Agent activation failed: $activate_err"
+    return 1
+  fi
+
+  # Confirm the activation took effect (async on some orgs).
+  local attempt
+  for attempt in {1..3}; do
+    active_count=$(pm_bot_active_version_count "$org_alias")
+    [[ "$active_count" -ge 1 ]] && return 0
+    [[ $attempt -lt 3 ]] && sleep 5
+  done
+
+  # sf agent activate returned success; treat as activated even if the
+  # confirmation query lagged.
+  return 0
+}

package/skills/sales-agentforce-pipeline-management-configure/scripts/shared/flow-builder.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# shared/flow-builder.sh — build the suggestion flow's field collection from a
+# selected set of Opportunity fields.
+#
+# The base flow template (assets/pipeline_management_flow.flow-meta.xml) ships
+# with a hardcoded AddOppFieldsToCollection assignment wiring BOTH NextStep and
+# StageName. Historically setup deployed both and then STRIPPED the unwanted one
+# (see strip_flow_field in setup-all.sh, still used for the repair path). For a
+# greenfield setup we instead build the flow with ONLY the selected fields from
+# the start — no deploy-then-strip round trip.
+#
+# This file only DEFINES a function; it makes no org calls and mutates no files
+# when sourced. build_field_collection reads the base template and writes a NEW
+# output file; it never edits the template in place.
+
+# build_field_collection <comma-separated-fields> <base-template> <output-file>
+#
+# Rewrites the AddOppFieldsToCollection assignment so its <assignmentItems>
+# contain exactly the given fields (in order, de-duplicated by the caller).
+# Uses python3 for a namespace-safe edit — the same requirement as
+# strip_flow_field. Returns non-zero (without writing) if python3 is missing,
+# the template is unreadable, the assignment/fields are absent, or the write
+# fails, so callers can fall back rather than deploy a corrupt/empty flow.
+#
+# A zero-item AddOppFieldsToCollection is INVALID Flow metadata and fails to
+# deploy, so this function refuses to write when the field list is empty.
+build_field_collection() {
+  local fields="$1" base_template="$2" output_file="$3"
+
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "  [FAIL] python3 not available — cannot build flow field collection." >&2
+    return 1
+  fi
+  if [[ ! -f "$base_template" ]]; then
+    echo "  [FAIL] Base flow template not found: $base_template" >&2
+    return 1
+  fi
+
+  python3 - "$base_template" "$output_file" "$fields" <<'PYEOF'
+import sys, xml.etree.ElementTree as ET
+
+base_template, output_file, raw_fields = sys.argv[1], sys.argv[2], sys.argv[3]
+
+# Order-preserving de-dup of trimmed, non-empty field names.
+fields = []
+for f in raw_fields.split(","):
+    f = f.strip()
+    if f and f not in fields:
+        fields.append(f)
+
+if not fields:
+    sys.stderr.write("  [FAIL] No fields provided — refusing to write an empty AddOppFieldsToCollection.\n")
+    sys.exit(2)
+
+ns = "http://soap.sforce.com/2006/04/metadata"
+ET.register_namespace("", ns)
+try:
+    tree = ET.parse(base_template)
+except Exception as e:  # noqa: BLE001
+    sys.stderr.write("  [FAIL] Could not parse base flow template: %s\n" % e)
+    sys.exit(3)
+
+root = tree.getroot()
+q = lambda t: "{%s}%s" % (ns, t)
+
+target = None
+for assign in root.findall(q("assignments")):
+    name_elem = assign.find(q("name"))
+    if name_elem is not None and name_elem.text == "AddOppFieldsToCollection":
+        target = assign
+        break
+
+if target is None:
+    sys.stderr.write("  [FAIL] AddOppFieldsToCollection assignment not found in template.\n")
+    sys.exit(4)
+
+# Drop existing assignmentItems, then rebuild from the selected fields.
+for item in list(target.findall(q("assignmentItems"))):
+    target.remove(item)
+
+# The FlowAssignment schema requires every <assignmentItems> to be contiguous
+# and positioned BEFORE <connector>. A plain ET.SubElement(target, ...) appends
+# to the end of the element — AFTER <connector> when the template has one — which
+# the Metadata API rejects with "Element assignmentItems is duplicated at this
+# location". Find the connector's index and insert each new block just before it
+# (falling back to append when there is no connector).
+conn_idx = next((i for i, c in enumerate(list(target)) if c.tag == q("connector")), None)
+insert_at = conn_idx
+for field in fields:
+    item = ET.Element(q("assignmentItems"))
+    ref = ET.SubElement(item, q("assignToReference"))
+    ref.text = "OpportunityFields"
+    op = ET.SubElement(item, q("operator"))
+    op.text = "Add"
+    val = ET.SubElement(item, q("value"))
+    sv = ET.SubElement(val, q("stringValue"))
+    sv.text = field
+    if insert_at is None:
+        target.append(item)
+    else:
+        target.insert(insert_at, item)
+        insert_at += 1
+
+try:
+    tree.write(output_file, xml_declaration=True, encoding="UTF-8")
+except Exception as e:  # noqa: BLE001
+    sys.stderr.write("  [FAIL] Could not write flow output file: %s\n" % e)
+    sys.exit(5)
+
+sys.exit(0)
+PYEOF
+}
+
+# strip_flow_field <flow-file> <field> — remove the matching <assignmentItems>
+# from the AddOppFieldsToCollection assignment of an EXISTING flow file, in place.
+# This is the "fix method" used by the REPAIR path (a flow already deployed with
+# fields the admin no longer wants). Greenfield never strips — it builds only the
+# selected fields via build_field_collection. Requires python3 for a
+# namespace-safe edit; if it is unavailable the field is left wired rather than
+# risk corrupting the XML with a regex. Returns 0 if a field was removed, 2 if
+# the field was not present (nothing to strip), non-zero on error.
+strip_flow_field() {
+  local flow_file="$1" field="$2"
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "  [WARN] python3 not available — cannot strip '$field' from the flow; leaving it wired." >&2
+    return 1
+  fi
+  python3 - "$flow_file" "$field" <<'PYEOF'
+import sys, xml.etree.ElementTree as ET
+flow_file, field = sys.argv[1], sys.argv[2]
+ns = "http://soap.sforce.com/2006/04/metadata"
+ET.register_namespace("", ns)
+tree = ET.parse(flow_file)
+root = tree.getroot()
+q = lambda t: "{%s}%s" % (ns, t)
+removed = 0
+for assign in root.findall(q("assignments")):
+    name = assign.find(q("name"))
+    if name is None or name.text != "AddOppFieldsToCollection":
+        continue
+    for item in list(assign.findall(q("assignmentItems"))):
+        sv = item.find("%s/%s" % (q("value"), q("stringValue")))
+        if sv is not None and sv.text == field:
+            assign.remove(item)
+            removed += 1
+if removed:
+    tree.write(flow_file, xml_declaration=True, encoding="UTF-8")
+sys.exit(0 if removed else 2)
+PYEOF
+}
+
+# add_flow_field <flow-file> <field> — idempotently ADD a field's <assignmentItems>
+# to the AddOppFieldsToCollection assignment of an EXISTING flow file, in place.
+# The symmetric counterpart to strip_flow_field, used by the REPAIR path to wire a
+# newly-selected field into an already-deployed flow without a full rebuild (a full
+# rebuild would discard the org-specific SalesManagementAgentTemplate constant the
+# retrieved flow carries). No-op if the field is already wired. Returns 0 if added,
+# 2 if it was already present, non-zero on error.
+add_flow_field() {
+  local flow_file="$1" field="$2"
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "  [WARN] python3 not available — cannot add '$field' to the flow." >&2
+    return 1
+  fi
+  python3 - "$flow_file" "$field" <<'PYEOF'
+import sys, xml.etree.ElementTree as ET
+flow_file, field = sys.argv[1], sys.argv[2]
+ns = "http://soap.sforce.com/2006/04/metadata"
+ET.register_namespace("", ns)
+tree = ET.parse(flow_file)
+root = tree.getroot()
+q = lambda t: "{%s}%s" % (ns, t)
+target = None
+for assign in root.findall(q("assignments")):
+    name = assign.find(q("name"))
+    if name is not None and name.text == "AddOppFieldsToCollection":
+        target = assign
+        break
+if target is None:
+    sys.stderr.write("  [FAIL] AddOppFieldsToCollection assignment not found.\n")
+    sys.exit(4)
+children = list(target)
+last_ai_idx = -1
+for idx, item in enumerate(children):
+    if item.tag != q("assignmentItems"):
+        continue
+    last_ai_idx = idx
+    sv = item.find("%s/%s" % (q("value"), q("stringValue")))
+    if sv is not None and sv.text == field:
+        sys.exit(2)  # already wired
+
+# Build the new assignmentItems block.
+item = ET.Element(q("assignmentItems"))
+ref = ET.SubElement(item, q("assignToReference")); ref.text = "OpportunityFields"
+op = ET.SubElement(item, q("operator")); op.text = "Add"
+val = ET.SubElement(item, q("value"))
+sv = ET.SubElement(val, q("stringValue")); sv.text = field
+
+# The FlowAssignment schema requires every <assignmentItems> to be contiguous
+# and positioned before <connector>. A plain append() lands the new block at
+# the end of the element — AFTER <connector> when one exists — which the
+# Metadata API rejects with "Element assignmentItems is duplicated at this
+# location". Insert immediately after the last existing assignmentItems; if
+# there are none, insert just before <connector> (else fall back to append).
+if last_ai_idx >= 0:
+    target.insert(last_ai_idx + 1, item)
+else:
+    conn_idx = next((i for i, c in enumerate(children) if c.tag == q("connector")), None)
+    if conn_idx is not None:
+        target.insert(conn_idx, item)
+    else:
+        target.append(item)
+tree.write(flow_file, xml_declaration=True, encoding="UTF-8")
+sys.exit(0)
+PYEOF
+}
+
+# flow_wired_fields <flow-file> — print the field API names currently wired into
+# AddOppFieldsToCollection, one per line (in document order). Used by the repair
+# path to diff the deployed flow against the admin's selected set.
+flow_wired_fields() {
+  local flow_file="$1"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$flow_file" <<'PYEOF'
+import sys, xml.etree.ElementTree as ET
+ns = "http://soap.sforce.com/2006/04/metadata"
+tree = ET.parse(sys.argv[1])
+q = lambda t: "{%s}%s" % (ns, t)
+for assign in tree.getroot().findall(q("assignments")):
+    name = assign.find(q("name"))
+    if name is None or name.text != "AddOppFieldsToCollection":
+        continue
+    for item in assign.findall(q("assignmentItems")):
+        sv = item.find("%s/%s" % (q("value"), q("stringValue")))
+        if sv is not None and sv.text:
+            print(sv.text)
+PYEOF
+}