@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-work-skill-routing-configure/scripts/configure-and-report.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# configure-and-report.sh - author a WorkSkillRouting rule (field-value -> required Omni Skill) for a related entity via the Metadata API; detect-before-write, idempotent, graceful-degrade when the feature is unavailable. Args, env, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 5 ]; then
+  echo '{"error":"Usage: bash configure-and-report.sh <org-alias> <related_entity> <field> <skill> <value> [rule_master_label]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+RELATED_ENTITY="$2"
+FIELD="$3"
+SKILL="$4"
+VALUE="$5"
+MASTER_LABEL_EXPLICIT=false
+{ [ -n "${6:-}" ] || [ -n "${RULE_MASTER_LABEL:-}" ]; } && MASTER_LABEL_EXPLICIT=true
+IS_ACTIVE_EXPLICIT=false
+[ -n "${IS_ACTIVE:-}" ] && IS_ACTIVE_EXPLICIT=true
+RULE_MASTER_LABEL="${6:-${RULE_MASTER_LABEL:-$RELATED_ENTITY Skill Routing}}"
+
+RULE_DN="${RULE_DEVELOPER_NAME:-$RELATED_ENTITY}"
+IS_ACTIVE="${IS_ACTIVE:-true}"
+SKILL_LEVEL="${SKILL_LEVEL:-}"
+SKILL_PRIORITY="${SKILL_PRIORITY:-}"
+IS_ADDITIONAL_SKILL="${IS_ADDITIONAL_SKILL:-}"
+
+# ---- validation (reject before any sf call) ----
+if ! [[ "$RELATED_ENTITY" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid related_entity '$RELATED_ENTITY'. Must be an sObject API name (letters, digits, underscores; max 80).\"}" >&2
+  exit 1
+fi
+if ! [[ "$FIELD" =~ ^[A-Za-z][A-Za-z0-9_.]{0,120}$ ]]; then
+  echo "{\"error\":\"Invalid field '$FIELD'. Use a field API name, optionally Entity.Field (letters, digits, underscores, dots).\"}" >&2
+  exit 1
+fi
+if ! [[ "$SKILL" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid skill '$SKILL'. Must be a Skill DeveloperName (letters, digits, underscores; max 80).\"}" >&2
+  exit 1
+fi
+if ! [[ "$VALUE" =~ ^[A-Za-z0-9][A-Za-z0-9\ _./-]{0,254}$ ]]; then
+  echo "{\"error\":\"Invalid value '$VALUE'. Provide a plain field value (letters, digits, space, . _ / -); XML-reserved characters are not supported.\"}" >&2
+  exit 1
+fi
+if ! [[ "$RULE_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid RULE_DEVELOPER_NAME '$RULE_DN'.\"}" >&2
+  exit 1
+fi
+if ! [[ "$RULE_MASTER_LABEL" =~ ^[A-Za-z0-9][A-Za-z0-9\ _-]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid rule_master_label '$RULE_MASTER_LABEL'.\"}" >&2
+  exit 1
+fi
+if [ "$IS_ACTIVE" != "true" ] && [ "$IS_ACTIVE" != "false" ]; then
+  echo "{\"error\":\"Invalid IS_ACTIVE '$IS_ACTIVE' - must be true or false.\"}" >&2
+  exit 1
+fi
+if [ -n "$SKILL_LEVEL" ] && { ! [[ "$SKILL_LEVEL" =~ ^[0-9]+$ ]] || [ "$SKILL_LEVEL" -gt 10 ]; }; then
+  echo "{\"error\":\"Invalid SKILL_LEVEL '$SKILL_LEVEL' - must be an integer 0..10.\"}" >&2
+  exit 1
+fi
+if [ -n "$SKILL_PRIORITY" ] && { ! [[ "$SKILL_PRIORITY" =~ ^[0-9]+$ ]] || [ "$SKILL_PRIORITY" -gt 10 ]; }; then
+  echo "{\"error\":\"Invalid SKILL_PRIORITY '$SKILL_PRIORITY' - must be an integer 0..10.\"}" >&2
+  exit 1
+fi
+if [ -n "$IS_ADDITIONAL_SKILL" ] && [ "$IS_ADDITIONAL_SKILL" != "true" ] && [ "$IS_ADDITIONAL_SKILL" != "false" ]; then
+  echo "{\"error\":\"Invalid IS_ADDITIONAL_SKILL '$IS_ADDITIONAL_SKILL' - must be true or false.\"}" >&2
+  exit 1
+fi
+
+# The Metadata API requires WorkSkillRoutingAttribute.field to be entity-qualified.
+# Bare standard fields are otherwise resolved as CustomField metadata and fail to deploy.
+if [[ "$FIELD" != *.* ]]; then
+  FIELD="${RELATED_ENTITY}.${FIELD}"
+fi
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated. Run: sf org login web -a $ORG -r <my-domain-url>\"}" >&2
+  exit 1
+fi
+
+emit_blocked() {
+  local msg="$1"; local target_skill="${2:-}"
+  local manual_actions='[]'
+  if [ -n "$target_skill" ]; then
+    manual_actions=$(jq -n --arg ts "$target_skill" '[{id:"MISSING_PREREQ",title:"Run prerequisite skill",target_skill:$ts}]')
+  fi
+  jq -n --arg msg "$msg" --arg rdn "$RULE_DN" --arg ent "$RELATED_ENTITY" --argjson ma "$manual_actions" \
+    '{skill:"service-omni-work-skill-routing-configure",status:"blocked",
+      rule:{developer_name:$rdn,related_entity:$ent,state:"not_deployed"},
+      attribute:null,deploy_id:null,manual_actions:$ma,blocking_issue:$msg}'
+  exit 1
+}
+
+emit_plan() {
+  local detail="$1"
+  jq -n --arg detail "$detail" --arg rdn "$RULE_DN" --arg ent "$RELATED_ENTITY" \
+    '{skill:"service-omni-work-skill-routing-configure",status:"action_needed",plan_mode:true,
+      plan_detail:$detail,rule:{developer_name:$rdn,related_entity:$ent},manual_actions:[],blocking_issue:null}'
+  exit 0
+}
+
+# Step 1 - Organization + safe_to_write guard
+ORG_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" --json 2>/dev/null) \
+  || emit_blocked "Failed to query Organization for the safe_to_write guard."
+IS_SANDBOX=$(echo "$ORG_JSON" | jq -r '.result.records[0].IsSandbox')
+TRIAL_EXP=$(echo "$ORG_JSON"  | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON"   | jq -r '.result.records[0].OrganizationType')
+SAFE_TO_WRITE=false
+if [ "$IS_SANDBOX" = "true" ] || [ "$TRIAL_EXP" != "null" ] \
+   || [ "$ORG_TYPE" = "Developer Edition" ] || [ "$ORG_TYPE" = "Base Edition" ]; then
+  SAFE_TO_WRITE=true
+fi
+[ "$SAFE_TO_WRITE" = "true" ] || emit_blocked "Refusing to author a routing rule on a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org."
+
+# Step 2 - Referenced Skill must exist (a WorkSkillRoutingAttribute.skill points at a Skill DeveloperName)
+SKILL_JSON=$(sf data query --target-org "$ORG" --json \
+  --query "SELECT Id FROM Skill WHERE DeveloperName='$SKILL'" 2>/dev/null || echo '{}')
+SKILL_COUNT=$(echo "$SKILL_JSON" | jq -r '.result.records | length' 2>/dev/null || echo 0)
+[ "${SKILL_COUNT:-0}" -ge 1 ] || emit_blocked "Referenced Skill '$SKILL' does not exist; deploy it first so the rule can bind to it." "service-omni-skills-based-routing-configure"
+
+# A metadata deploy replaces the full one-per-entity rule. Read and merge the
+# current attribute array so adding Origin does not erase an existing Priority rule.
+MERGE_MODE=true
+[ "${WSR_REPLACE:-}" = "1" ] && MERGE_MODE=false
+EXISTING_ATTRS='[]'
+MERGED_FROM_EXISTING=false
+if [ "$MERGE_MODE" = "true" ]; then
+  WSR_META_JSON=$(sf data query --target-org "$ORG" --use-tooling-api --json \
+    --query "SELECT Metadata FROM WorkSkillRouting WHERE DeveloperName='$RULE_DN'" 2>/dev/null || true)
+  if echo "$WSR_META_JSON" | jq -e '.result.totalSize == 1' >/dev/null 2>&1; then
+    MERGED_FROM_EXISTING=true
+    EXISTING_ATTRS=$(echo "$WSR_META_JSON" | jq -c '.result.records[0].Metadata.workSkillRoutingAttributes // []')
+    PRESERVED_LABEL=$(echo "$WSR_META_JSON" | jq -r '.result.records[0].Metadata.masterLabel // ""')
+    PRESERVED_ACTIVE=$(echo "$WSR_META_JSON" | jq -r '.result.records[0].Metadata.isActive // empty')
+    [ "$MASTER_LABEL_EXPLICIT" = "true" ] || [ -z "$PRESERVED_LABEL" ] || RULE_MASTER_LABEL="$PRESERVED_LABEL"
+    [ "$IS_ACTIVE_EXPLICIT" = "true" ] || [ -z "$PRESERVED_ACTIVE" ] || IS_ACTIVE="$PRESERVED_ACTIVE"
+  elif echo "$WSR_META_JSON" | jq -e '.result.totalSize == 0' >/dev/null 2>&1; then
+    :
+  elif ! echo "$WSR_META_JSON" | grep -qiE 'INVALID_TYPE|not available|no such|Cannot find'; then
+    emit_blocked "Could not read existing WorkSkillRouting '$RULE_DN' for a merge. Refusing a destructive whole-rule replace; retry the read or set WSR_REPLACE=1 to overwrite intentionally."
+  fi
+fi
+
+NEW_ATTR=$(jq -n \
+  --arg field "$FIELD" --arg skill "$SKILL" --arg value "$VALUE" \
+  --arg lvl "$SKILL_LEVEL" --arg pri "$SKILL_PRIORITY" --arg add "$IS_ADDITIONAL_SKILL" \
+  '{field:$field,skill:$skill,value:$value}
+   + (if $add=="" then {} else {isAdditionalSkill:($add=="true")} end)
+   + (if $lvl=="" then {} else {skillLevel:($lvl|tonumber)} end)
+   + (if $pri=="" then {} else {skillPriority:($pri|tonumber)} end)')
+MERGED_ATTRS=$(jq -c -n --argjson existing "$EXISTING_ATTRS" --argjson new "$NEW_ATTR" \
+  '($existing | map(select((.field==$new.field and .value==$new.value) | not))) + [$new]')
+ATTR_COUNT=$(echo "$MERGED_ATTRS" | jq -r 'length')
+PRESERVED_COUNT=$((ATTR_COUNT - 1))
+
+# PLAN_ONLY - read-only; report intent and stop before any write.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  emit_plan "Would deploy WorkSkillRouting '$RULE_DN' on $RELATED_ENTITY (isActive=$IS_ACTIVE) mapping $FIELD='$VALUE' -> Skill '$SKILL'."
+fi
+
+# Step 3 - Materialize the WorkSkillRouting in XSD (alphabetical) order
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
+cp "$SCRIPT_DIR/../assets/sfdx-project.json" "$WORK/sfdx-project.json" 2>/dev/null \
+  || echo '{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"66.0"}' > "$WORK/sfdx-project.json"
+WSR_DIR="$WORK/force-app/main/default/workSkillRoutings"
+mkdir -p "$WSR_DIR"
+
+ATTR_XML=$(echo "$MERGED_ATTRS" | jq -r '
+  def xe: tostring | gsub("&";"&amp;") | gsub("<";"&lt;") | gsub(">";"&gt;");
+  .[] |
+  "    <workSkillRoutingAttributes>",
+  "        <field>\(.field|xe)</field>",
+  (if has("isAdditionalSkill") then "        <isAdditionalSkill>\(.isAdditionalSkill)</isAdditionalSkill>" else empty end),
+  "        <skill>\(.skill|xe)</skill>",
+  (if .skillLevel != null then "        <skillLevel>\(.skillLevel)</skillLevel>" else empty end),
+  (if .skillPriority != null then "        <skillPriority>\(.skillPriority)</skillPriority>" else empty end),
+  "        <value>\(.value|xe)</value>",
+  "    </workSkillRoutingAttributes>"
+')
+
+cat > "$WSR_DIR/${RULE_DN}.workSkillRouting-meta.xml" <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<WorkSkillRouting xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isActive>${IS_ACTIVE}</isActive>
+    <masterLabel>${RULE_MASTER_LABEL}</masterLabel>
+    <relatedEntity>${RELATED_ENTITY}</relatedEntity>
+${ATTR_XML}
+</WorkSkillRouting>
+XML
+
+# Step 4 - Deploy (async + poll to terminal state)
+START_JSON=$(cd "$WORK" && sf project deploy start --target-org "$ORG" \
+  --metadata "WorkSkillRouting:${RULE_DN}" --async --json 2>/dev/null || true)
+DEPLOY_ID=$(echo "$START_JSON" | jq -r '.result.id // ""' 2>/dev/null)
+DEPLOY_JSON="$START_JSON"
+
+if [ -n "$DEPLOY_ID" ] && [ "$DEPLOY_ID" != "null" ]; then
+  POLL_STATUS=""
+  for _ in $(seq 1 60); do
+    REPORT_JSON=$(cd "$WORK" && sf project deploy report --job-id "$DEPLOY_ID" --target-org "$ORG" --json 2>/dev/null || true)
+    CUR_STATUS=$(echo "$REPORT_JSON" | jq -r '.result.status // ""' 2>/dev/null)
+    case "$CUR_STATUS" in
+      Succeeded|Failed|SucceededPartial|Canceled) DEPLOY_JSON="$REPORT_JSON"; POLL_STATUS="$CUR_STATUS"; break ;;
+    esac
+    sleep 15
+  done
+  [ -n "$POLL_STATUS" ] || emit_blocked "WorkSkillRouting deploy job $DEPLOY_ID did not reach a terminal state within the poll budget. Not reporting success."
+fi
+
+DEPLOY_SUCCESS=$(echo "$DEPLOY_JSON" | jq -r '.result.success // false' 2>/dev/null)
+DEPLOY_ID=$(echo "$DEPLOY_JSON"      | jq -r '.result.id      // ""'    2>/dev/null)
+
+if [ "$DEPLOY_SUCCESS" != "true" ]; then
+  FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
+  [ -n "$FAILURES" ] && [ "$FAILURES" != "null" ] || FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.message // .result.errorMessage // "Unknown deploy error"' 2>/dev/null)
+  case "$FAILURES" in
+    *INVALID_TYPE*|*"Cannot find"*|*"not available"*|*"WorkSkillRouting"*)
+      emit_blocked "WorkSkillRouting is not available on this org (skills-based routing may be off, or the feature is not provisioned on this trial/CDO): $FAILURES" "service-omni-base-settings-configure" ;;
+    *"$SKILL"*)
+      emit_blocked "Deploy failed: Skill '$SKILL' could not be resolved by the rule. $FAILURES" "service-omni-skills-based-routing-configure" ;;
+    *) emit_blocked "WorkSkillRouting deploy failed: $FAILURES" ;;
+  esac
+fi
+
+STATE_WSR=$(echo "$DEPLOY_JSON" | jq -r --arg fn "$RULE_DN" \
+  '.result.files[] | select(.fullName==$fn and .type=="WorkSkillRouting") | .state' 2>/dev/null | head -1)
+STATE_WSR="${STATE_WSR:-unknown}"
+case "$STATE_WSR" in
+  Created|Changed|Unchanged) ;;
+  *) emit_blocked "Deploy reported success overall but WorkSkillRouting '$RULE_DN' has an unrecognized/absent state \"$STATE_WSR\" (expected Created, Changed, or Unchanged). Not reporting success." ;;
+esac
+
+STATUS="reused"
+[ "$STATE_WSR" = "Created" ] && STATUS="created"
+[ "$STATE_WSR" = "Changed" ] && STATUS="updated"
+
+jq -n \
+  --arg status "$STATUS" \
+  --arg rdn "$RULE_DN" --arg lbl "$RULE_MASTER_LABEL" --arg ent "$RELATED_ENTITY" --arg act "$IS_ACTIVE" --arg state "$STATE_WSR" \
+  --arg field "$FIELD" --arg skill "$SKILL" --arg value "$VALUE" \
+  --arg lvl "$SKILL_LEVEL" --arg pri "$SKILL_PRIORITY" --arg add "$IS_ADDITIONAL_SKILL" \
+  --arg deploy_id "$DEPLOY_ID" \
+  --argjson merged_from_existing "$MERGED_FROM_EXISTING" \
+  --argjson attribute_count "$ATTR_COUNT" \
+  --argjson preserved_count "$PRESERVED_COUNT" \
+  '{
+    skill: "service-omni-work-skill-routing-configure",
+    status: $status,
+    rule: {developer_name:$rdn, master_label:$lbl, related_entity:$ent, is_active:($act=="true"), state:$state},
+    merge: {merged_from_existing:$merged_from_existing, attribute_count:$attribute_count, preserved_count:$preserved_count},
+    attribute: {
+      field:$field, skill:$skill, value:$value,
+      skill_level:(if $lvl=="" then null else ($lvl|tonumber) end),
+      skill_priority:(if $pri=="" then null else ($pri|tonumber) end),
+      is_additional_skill:(if $add=="" then null else ($add=="true") end)
+    },
+    deploy_id: (if $deploy_id=="" then null else $deploy_id end),
+    manual_actions: [],
+    blocking_issue: null
+  }'

package/skills/service-omni-work-skill-routing-configure/scripts/tests/_bootstrap.py

@@ -0,0 +1,121 @@
+"""Shared paths + fake-`sf` harness for the work-skill-routing contract suite.
+
+Drives ``configure-and-report.sh`` via ``subprocess`` and asserts on exit codes + emitted JSON.
+Org-free and network-free. ``jq`` comes from the real PATH.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SKILL_DIR = "service-omni-work-skill-routing-configure"
+SCRIPT = f"{SKILL_DIR}/scripts/configure-and-report.sh"
+
+# PRODUCTION org - safe_to_write must refuse before any deploy.
+_FAKE_SF_PROD = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      echo '{"status":0,"result":{"records":[{"IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}]}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+    exit 0;;
+  "project deploy") echo '{"status":1,"result":{"success":false},"message":"FAKE_SF_DEPLOY_SHOULD_NOT_BE_REACHED"}'; exit 1;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+# SANDBOX org. Tunables:
+#   FAKE_STATE_WSR   -> Created|Changed|Unchanged (default Created).
+#   FAKE_SKILL_PRESENT -> 1|0 (default 1); 0 blocks on the missing-Skill prereq.
+#   FAKE_DEPLOY_FAIL=1 -> deploy fails with a feature-unavailable (INVALID_TYPE) problem.
+#   FAKE_RULE_DN     -> fullName echoed in the report (default Case).
+_FAKE_SF_SANDBOX = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+STATE_WSR="${FAKE_STATE_WSR:-Created}"
+RULE_DN="${FAKE_RULE_DN:-Case}"
+if [ -n "${FAKE_SF_CALLLOG:-}" ]; then printf '%s\n' "$args" >> "$FAKE_SF_CALLLOG"; fi
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      echo '{"status":0,"result":{"records":[{"IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+    elif printf '%s' "$args" | grep -q "FROM WorkSkillRouting"; then
+      if [ "${FAKE_WSR_INCONCLUSIVE:-0}" = "1" ]; then
+        echo '{"status":1,"message":"Transient failure reading WorkSkillRouting metadata"}'
+      elif [ "${FAKE_WSR_EXISTING:-0}" = "1" ]; then
+        if [ "${FAKE_WSR_NULL_OPTIONALS:-0}" = "1" ]; then
+          echo '{"status":0,"result":{"totalSize":1,"records":[{"Metadata":{"masterLabel":"Existing Label","isActive":true,"relatedEntity":"Case","workSkillRoutingAttributes":[{"field":"Case.Priority","skill":"Priority_Support","value":"High","skillLevel":null,"skillPriority":null}]}}]}}'
+        else
+          echo '{"status":0,"result":{"totalSize":1,"records":[{"Metadata":{"masterLabel":"Existing Label","isActive":true,"relatedEntity":"Case","workSkillRoutingAttributes":[{"field":"Case.Priority","skill":"Priority_Support","value":"High"}]}}]}}'
+        fi
+      else
+        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+      fi
+    elif printf '%s' "$args" | grep -q "FROM Skill"; then
+      if [ "${FAKE_SKILL_PRESENT:-1}" = "1" ]; then
+        echo '{"status":0,"result":{"records":[{"Id":"0C9xx0000000001"}],"totalSize":1}}'
+      else
+        echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+      fi
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+    exit 0;;
+  "project deploy")
+    if printf '%s' "$args" | grep -q "report"; then
+      if grep -R -q '>null<' force-app/main/default/workSkillRoutings 2>/dev/null; then
+        echo '{"status":0,"result":{"success":false,"id":"0AfXX0000000001","status":"Failed","details":{"componentFailures":[{"problem":"null is not a valid value for the type xsd:int"}]}}}'
+      elif [ "${FAKE_DEPLOY_FAIL:-0}" = "1" ]; then
+        echo '{"status":0,"result":{"success":false,"id":"0AfXX0000000001","status":"Failed","details":{"componentFailures":[{"problem":"INVALID_TYPE: WorkSkillRouting not available"}]}}}'
+      else
+        printf '{"status":0,"result":{"success":true,"id":"0AfXX0000000001","status":"Succeeded","files":[{"fullName":"%s","type":"WorkSkillRouting","state":"%s"}]}}' "$RULE_DN" "$STATE_WSR"
+      fi
+    else
+      echo '{"status":0,"result":{"id":"0AfXX0000000001","status":"Queued"}}'
+    fi
+    exit 0;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+
+def run(args, path_prefix=None, scrub_sf=False, extra_env=None):
+    env = dict(os.environ)
+    if scrub_sf:
+        kept = [d for d in env.get("PATH", "").split(os.pathsep)
+                if d and not os.path.exists(os.path.join(d, "sf"))]
+        env["PATH"] = os.pathsep.join(kept)
+    if path_prefix:
+        env["PATH"] = path_prefix + os.pathsep + env.get("PATH", "")
+    if extra_env:
+        env.update({k: str(v) for k, v in extra_env.items()})
+    proc = subprocess.run(
+        ["bash", str(SKILLS_ROOT / SCRIPT), *args],
+        capture_output=True, text=True, env=env, cwd=str(SKILLS_ROOT),
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+class FakeSf:
+    def __init__(self, body=_FAKE_SF_PROD):
+        self._body = body
+        self._tmp = None
+
+    def __enter__(self):
+        self._tmp = tempfile.mkdtemp(prefix="wsr-fake-sf-")
+        sf = Path(self._tmp) / "sf"
+        sf.write_text(self._body)
+        sf.chmod(0o755)
+        return self._tmp
+
+    def __exit__(self, *exc):
+        import shutil
+        if self._tmp:
+            shutil.rmtree(self._tmp, ignore_errors=True)

package/skills/service-omni-work-skill-routing-configure/scripts/tests/test_work_skill_routing_contracts.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-work-skill-routing-configure/scripts/configure-and-report.sh."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import (  # noqa: E402
+    FakeSf,
+    _FAKE_SF_PROD,
+    _FAKE_SF_SANDBOX,
+    run,
+)
+
+
+def _last_json(out: str) -> dict:
+    dec = json.JSONDecoder()
+    obj, i, n = None, 0, len(out)
+    while i < n:
+        if out[i] in "{[":
+            try:
+                cand, end = dec.raw_decode(out, i)
+                if isinstance(cand, dict):
+                    obj = cand
+                i = end
+                continue
+            except json.JSONDecodeError:
+                pass
+        i += 1
+    assert obj is not None, f"no JSON object found in output:\n{out}"
+    return obj
+
+
+class InputContractTests(unittest.TestCase):
+    def test_missing_args_rejected(self):
+        rc, out = run(["myorg", "Case", "Origin"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Usage", out)
+
+    def test_injection_shaped_skill_rejected(self):
+        rc, out = run(["myorg", "Case", "Origin", "Bad; DROP", "Phone"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid skill", out)
+
+    def test_xml_injection_value_rejected(self):
+        rc, out = run(["myorg", "Case", "Origin", "Voice", "<x>&bad"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid value", out)
+
+    def test_bad_related_entity_rejected(self):
+        rc, out = run(["myorg", "Case Origin", "Origin", "Voice", "Phone"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid related_entity", out)
+
+    def test_out_of_range_skill_level_rejected(self):
+        rc, out = run(["myorg", "Case", "Origin", "Voice", "Phone"], scrub_sf=True,
+                      extra_env={"SKILL_LEVEL": "11"})
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid SKILL_LEVEL", out)
+
+
+class ProductionGuardTests(unittest.TestCase):
+    def test_refuses_production_org(self):
+        with FakeSf(_FAKE_SF_PROD) as p:
+            rc, out = run(["prodorg", "Case", "Origin", "Voice", "Phone"], path_prefix=p)
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("production", v["blocking_issue"].lower())
+
+
+class ConfigureTests(unittest.TestCase):
+    def test_create_deploys_rule(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Case.Origin", "Voice", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_STATE_WSR": "Created"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "created", out)
+        self.assertEqual(v["rule"]["related_entity"], "Case", out)
+        self.assertEqual(v["attribute"]["skill"], "Voice", out)
+        self.assertEqual(v["attribute"]["value"], "Phone", out)
+
+    def test_bare_standard_field_is_entity_qualified(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Priority", "Voice", "High"], path_prefix=p,
+                          extra_env={"FAKE_STATE_WSR": "Created"})
+        self.assertEqual(rc, 0, out)
+        self.assertEqual(_last_json(out)["attribute"]["field"], "Case.Priority", out)
+
+    def test_reused_when_unchanged(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Origin", "Voice", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_STATE_WSR": "Unchanged"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "reused", out)
+
+    def test_blocks_when_referenced_skill_missing(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Origin", "Voice", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_SKILL_PRESENT": "0"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertTrue(any(a.get("target_skill") == "service-omni-skills-based-routing-configure"
+                            for a in v["manual_actions"]), out)
+
+    def test_graceful_degrade_when_feature_unavailable(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Origin", "Voice", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_DEPLOY_FAIL": "1"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("not available", v["blocking_issue"].lower())
+
+    def test_plan_only_reports_without_writing(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            calllog = str(Path(p) / "calls.log")
+            rc, out = run(["sandbox", "Case", "Origin", "Voice", "Phone"], path_prefix=p,
+                          extra_env={"PLAN_ONLY": "1", "FAKE_SF_CALLLOG": calllog})
+            log = Path(calllog).read_text() if Path(calllog).exists() else ""
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertTrue(v.get("plan_mode"), out)
+        self.assertEqual(v["status"], "action_needed", out)
+        self.assertNotIn("project deploy", log, "plan mode must not deploy")
+
+
+class MergeSafeTests(unittest.TestCase):
+    def test_preserves_existing_mapping(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Origin", "Voice_Support", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_WSR_EXISTING": "1", "FAKE_STATE_WSR": "Changed"})
+        self.assertEqual(rc, 0, out)
+        merge = _last_json(out)["merge"]
+        self.assertEqual(merge["attribute_count"], 2, out)
+        self.assertEqual(merge["preserved_count"], 1, out)
+
+    def test_omits_null_optional_values_from_preserved_mapping(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Origin", "Voice_Support", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_WSR_EXISTING": "1", "FAKE_WSR_NULL_OPTIONALS": "1",
+                                     "FAKE_STATE_WSR": "Changed"})
+        self.assertEqual(rc, 0, out)
+        self.assertEqual(_last_json(out)["merge"]["preserved_count"], 1, out)
+
+    def test_inconclusive_read_blocks_destructive_replace(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Case", "Origin", "Voice_Support", "Phone"], path_prefix=p,
+                          extra_env={"FAKE_WSR_INCONCLUSIVE": "1"})
+        self.assertEqual(rc, 1, out)
+        self.assertIn("WSR_REPLACE", _last_json(out)["blocking_issue"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)