@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-sidebar-configure/scripts/tests/test_sidebar_contracts.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-sidebar-configure/scripts/enable-and-report.sh.
+
+Run standalone: ``python3 test_sidebar_contracts.py`` (or under pytest / unittest discovery).
+"""
+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:
+    """Parse the last JSON object printed to stdout+stderr."""
+    dec = json.JSONDecoder()
+    obj, i, n = None, 0, len(out)
+    while i < n:
+        ch = out[i]
+        if ch 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):
+    """Argument guarantees must hold before any `sf` call (PATH has no sf)."""
+
+    def test_missing_org_rejected(self):
+        rc, out = run([], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Usage", out)
+
+    def test_injection_shaped_app_name_rejected(self):
+        rc, out = run(["myorg", "Bad Name; DROP"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid app_developer_name", out)
+
+
+class ProductionGuardTests(unittest.TestCase):
+    def test_refuses_production_org(self):
+        with FakeSf(_FAKE_SF_PROD) as p:
+            rc, out = run(["prodorg", "Demo_Console"], 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 AutoDetectTests(unittest.TestCase):
+    def test_blocks_when_no_console_app(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p, extra_env={"FAKE_CONSOLE_APPS": "0"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("No deployable custom Lightning console app", v["blocking_issue"])
+
+    def test_blocks_when_multiple_console_apps(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p, extra_env={"FAKE_CONSOLE_APPS": "2"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("explicit app_developer_name", v["blocking_issue"])
+
+    def test_adopts_single_console_app(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox"], path_prefix=p, extra_env={"FAKE_CONSOLE_APPS": "1"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["app_developer_name"], "Demo_Console", out)
+
+    def test_autodetect_uses_deployable_custom_application_metadata(self):
+        src = (Path(__file__).resolve().parents[1] / "enable-and-report.sh").read_text()
+        start = src.index("APP_METADATA_JSON=$(sf org list metadata")
+        block = src[start:src.index("APP_COUNT=", start)]
+        self.assertIn("--metadata-type CustomApplication", block)
+        self.assertIn('startswith("standard__") | not', block)
+        self.assertIn("<navType>Console</navType>", block)
+
+
+class EnableAndReuseTests(unittest.TestCase):
+    def test_enables_when_absent_and_verifies_roundtrip(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            rc, out = run(["sandbox", "Demo_Console"], path_prefix=p,
+                          extra_env={"FAKE_APP_PINNED": "0"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["status"], "enabled", out)
+        self.assertFalse(v["before"], out)
+        self.assertTrue(v["after"], out)
+        self.assertIsNotNone(v["deploy_id"], out)
+
+    def test_reused_when_already_pinned_without_deploy(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            calllog = str(Path(p) / "calls.log")
+            rc, out = run(["sandbox", "Demo_Console"], path_prefix=p,
+                          extra_env={"FAKE_APP_PINNED": "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.assertEqual(v["status"], "reused", out)
+        self.assertTrue(v["before"], out)
+        self.assertTrue(v["after"], out)
+        self.assertNotIn("project deploy", log, "reused path must not deploy")
+
+    def test_plan_only_reports_action_without_writing(self):
+        with FakeSf(_FAKE_SF_SANDBOX) as p:
+            calllog = str(Path(p) / "calls.log")
+            rc, out = run(["sandbox", "Demo_Console"], path_prefix=p,
+                          extra_env={"FAKE_APP_PINNED": "0", "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")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-skills-based-routing-configure/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: service-omni-skills-based-routing-configure
+description: "Use to make agents routable by Omni skills-based routing: ensure an Omni Skill exists, then assign it to each active agent through the classic Omni-Channel SkillUser junction. Idempotent — existing skills and user bindings are reused, and only missing bindings are created. Works on Service Cloud orgs without requiring Field Service. Triggers: set up skills-based routing agents, assign Omni skills to agents, make agents skill-routable, create an Omni skill and bind users, repair missing agent skill assignments. Do not use to author WorkSkillRouting rules, create agent users, or configure queues."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-agent-users-create"
+    - "service-omni-base-settings-configure"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-skills-based-routing-configure
+
+Make agents routable by Omni **skills-based routing (SBR)**. A routable agent needs the **Skill** and a **SkillUser** junction assigning that skill to the agent's user. `SkillUser` is the classic Omni-Channel model written by Setup > Skills > Assign Users and evaluated when work has skill requirements. This skill ensures both, idempotently, for one skill across a set of active agent users.
+
+`ServiceResource` and `ServiceResourceSkill` are the Field Service skill model. On a plain Service Cloud org, `ServiceResource.IsActive` is not writable or queryable, so a newly created resource remains inactive and the junction is rejected. This skill therefore uses the supported, license-appropriate `SkillUser` path.
+
+## Inputs
+
+```bash
+bash scripts/configure-and-report.sh <org-alias> <skill_developer_name> [agent_members_csv] [skill_master_label]
+```
+
+- `org-alias` (required).
+- `skill_developer_name` (required). The Omni `Skill` DeveloperName to ensure and bind (e.g. `Omni_Demo_Voice`).
+- `agent_members_csv` (optional). Comma-separated agents to make skill-routable — each token a Username (`…@…`) or a 15/18-char User Id (`005…`). May also be supplied via `AGENT_MEMBERS_CSV`. When omitted, the skill blocks (it will not guess which agents to skill).
+- `skill_master_label` (optional). MasterLabel used only when the skill must be created; defaults to a title-cased form of the DeveloperName.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
+- Omni-Channel base settings enabled with **skills-based routing** turned on (`service-omni-base-settings-configure`).
+- The named agents exist and are active (`service-omni-agent-users-create`).
+- The three-way `safe_to_write` production guard applies.
+
+## Run
+
+`configure-and-report.sh` proceeds in two idempotent phases, each detect-before-write:
+
+1. **Skill** — query `Skill` by DeveloperName. Present → reused; absent → deploy a `Skill` component via the Metadata API and re-query for its Id.
+2. **SkillUser** — query existing `SkillUser` records for the Skill and resolved users, then create only missing (`SkillId`, `UserId`) bindings via REST DML. A concurrent `DUPLICATE_VALUE` is reconciled as reused.
+
+## Behavior
+
+**Idempotent + non-destructive.** Existing skills and bindings are reused; the skill never deletes or reassigns anything it did not create, so re-runs converge without duplication. Only **active** users are resolved — an inactive user cannot be routed work, so it is reported rather than silently skilled.
+
+**Partial safety.** If some bindings succeed and others fail, the status is `partial` with per-agent errors in `blocking_issue`; the successful bindings are left in place (each junction is an independent write).
+
+## Output contract
+
+A single JSON object: `status` ∈ `configured` | `reused` | `partial` | `blocked`, `skill` (`{developer_name, id, state}`), `agents` (array of `{username, user_id, skill_binding_id, skill_binding_state}`), `created_counts`, `reused_counts`, `manual_actions`, `blocking_issue`.
+
+- `reused` — skill and all bindings already existed.
+- `configured` — at least one component created and all requested bindings now exist.
+- `partial` / `blocked` — see `blocking_issue`; `manual_actions` names the prerequisite skill when the cause is a missing precondition.
+
+## Limitations
+
+- One skill per invocation; run again per skill an agent set needs.
+- Does not author `WorkSkillRouting` rules or field-based skill criteria — that is a separate skill.
+- Does not create agent users, queues, or presence configuration.
+- `SkillUser.SkillLevel` is left at the platform default; forking the DML body is required to set explicit proficiency.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | Skill metadata vs Skill sObject, the SkillUser agent-binding model, and SBR base-setting prerequisites |
+| `scripts/tests/test_sbr_contracts.py` | When validating changes — run `python3 scripts/tests/test_sbr_contracts.py` from this skill directory |

package/skills/service-omni-skills-based-routing-configure/references/api-notes.md

@@ -0,0 +1,50 @@
+# API notes — service-omni-skills-based-routing-configure
+
+## The two objects skills-based routing needs
+
+| Object | API | Purpose |
+|---|---|---|
+| `Skill` | Metadata API (`Skill`) to create; `Skill` sObject to read | The skill definition. Skills are metadata-backed — they cannot be `INSERT`ed via DML, so a missing skill is created by deploying a `Skill` component, then re-queried for its Id. |
+| `SkillUser` | REST DML | Junction assigning a `Skill` to an agent `User`, matching Setup > Skills > Assign Users. Required: `SkillId`, `UserId`. |
+
+## Skill: metadata create, sObject read
+
+The `Skill` sObject exposes `Id`, `DeveloperName`, `MasterLabel` and is queryable, so detection is a
+SOQL read by DeveloperName. Creation is a Metadata API deploy of:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Skill xmlns="http://soap.sforce.com/2006/04/metadata">
+    <description>…</description>
+    <label>…</label>
+</Skill>
+```
+
+After the deploy the skill's Id is obtained by re-querying the sObject (the deploy response carries
+the fullName, not the record Id). A freshly-deployed skill may lag a moment before it is queryable;
+if the re-query returns nothing the skill blocks and asks for a re-run rather than binding to an
+empty Id.
+
+## SkillUser
+
+- The skill deduplicates `SkillUser` by `(SkillId, UserId)` and creates only missing bindings for
+  active users. `SkillLevel` is optional and remains at the platform default.
+- `SkillUser` is created through REST DML. A concurrent create can return `DUPLICATE_VALUE`; the
+  script reconciles that response as reused because the desired binding now exists.
+- `ServiceResourceSkill` is not used. It belongs to the Field Service model and requires an active
+  `ServiceResource`. Plain Service Cloud orgs do not expose a writable or queryable
+  `ServiceResource.IsActive`, so that path produces inactive resources and rejected bindings.
+
+## Prerequisite: base settings
+
+Skills-based routing must be enabled in Omni-Channel settings
+(`service-omni-base-settings-configure`) before skills route work. A Skill deploy can succeed while
+SBR is off, so the skill points the operator at the base-settings skill when the deploy fails with
+an SBR-disabled error.
+
+## Out of scope: WorkSkillRouting
+
+Authoring `WorkSkillRouting` rules (field-based skill criteria such as "add Voice when Case
+Priority = Medium") is a **separate** capability — it is a Tooling-API rule header
+(`WorkSkillRoutingStandardEntity`: `MasterLabel`, `DeveloperName`, `IsActive`) with skill-requirement
+and field-criteria children, and only one rule is permitted per entity. It is not created here.

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

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# configure-and-report.sh - make agents routable via skills-based routing: ensure a Skill and a SkillUser
+# binding per agent (the classic Omni-Channel agent-skill model); detect-before-write, idempotent.
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo '{"error":"Usage: bash configure-and-report.sh <org-alias> <skill_developer_name> [agent_members_csv] [skill_master_label]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+SKILL_DN="$2"
+AGENTS_CSV="${3:-${AGENT_MEMBERS_CSV:-}}"
+SKILL_LABEL_ARG="${4:-}"
+API_VERSION="v66.0"
+
+# Skill DeveloperName grammar: leading letter, then letters/digits/underscore, max 80.
+if ! [[ "$SKILL_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid skill_developer_name '$SKILL_DN'. Must start with a letter and contain only letters, digits, and underscores (max 80).\"}" >&2
+  exit 1
+fi
+
+if [ -z "$AGENTS_CSV" ]; then
+  echo '{"error":"No agents supplied. Pass agent_members_csv (Usernames and/or 005... User Ids) or set AGENT_MEMBERS_CSV."}' >&2
+  exit 1
+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
+
+# Default MasterLabel from DeveloperName (underscores -> spaces) when not supplied.
+if [ -n "$SKILL_LABEL_ARG" ]; then
+  SKILL_LABEL="$SKILL_LABEL_ARG"
+else
+  SKILL_LABEL=$(printf '%s' "$SKILL_DN" | tr '_' ' ')
+fi
+
+# Escape the five XML predefined entities so a caller-supplied SKILL_LABEL with & < > " ' cannot
+# break or inject into the hand-built Skill metadata XML below.
+xml_escape() {
+  local s="$1"
+  s="${s//&/&amp;}"; s="${s//</&lt;}"; s="${s//>/&gt;}"; s="${s//\"/&quot;}"; s="${s//\'/&apos;}"
+  printf '%s' "$s"
+}
+
+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 dn "$SKILL_DN" --argjson ma "$manual_actions" \
+    '{skill:"service-omni-skills-based-routing-configure",status:"blocked",
+      skill_configured:{developer_name:$dn,id:null,state:"not_created"},
+      agents:[],created_counts:{},reused_counts:{},manual_actions:$ma,blocking_issue:$msg}'
+  exit 1
+}
+
+emit_plan() {
+  local status="$1"; local detail="$2"
+  jq -n --arg status "$status" --arg detail "$detail" --arg dn "$SKILL_DN" \
+    '{skill:"service-omni-skills-based-routing-configure",status:$status,plan_mode:true,
+      plan_detail:$detail,skill_configured:{developer_name:$dn},manual_actions:[],blocking_issue:null}'
+  exit 0
+}
+
+# REST POST helper: echoes the created Id on success, empty on failure. Error detail is written to a
+# file because this function is called inside command substitution and shell variables would be lost.
+POST_ERR_FILE="$(mktemp)"
+trap 'rm -f "$POST_ERR_FILE"' EXIT
+post_err() { cat "$POST_ERR_FILE" 2>/dev/null || true; }
+rest_post() {
+  local sobject="$1"; local body="$2"
+  local stderr_f; stderr_f="$(mktemp)"
+  local res
+  res=$(sf api request rest --target-org "$ORG" \
+    "/services/data/$API_VERSION/sobjects/$sobject" --method POST --body "$body" 2>"$stderr_f" || true)
+  local ok; ok=$(echo "$res" | jq -r '.success // false' 2>/dev/null || echo false)
+  if [ "$ok" = "true" ]; then
+    : > "$POST_ERR_FILE"
+    echo "$res" | jq -r '.id'
+  else
+    local code msg
+    code=$(echo "$res" | jq -r 'if type=="array" then .[0].errorCode else .errorCode // "UNKNOWN" end' 2>/dev/null || echo UNKNOWN)
+    msg=$(echo "$res"  | jq -r 'if type=="array" then .[0].message   else .message   // "" end' 2>/dev/null || echo "")
+    if [ -z "$msg" ] || [ "$msg" = "null" ]; then
+      msg=$(printf '%s' "$res" | tr '\n' ' ' | head -c 200)
+      [ -n "$msg" ] || msg=$(grep -v '^Warning:' "$stderr_f" | head -1)
+      [ -n "$msg" ] || msg="no error detail returned by the sf CLI"
+    fi
+    printf '%s - %s' "$code" "$msg" > "$POST_ERR_FILE"
+    echo ""
+  fi
+  rm -f "$stderr_f"
+}
+
+# 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 configure skills-based routing 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 - Resolve active agents from the CSV (Usernames and/or 005... Ids)
+USERNAME_IN=""; ID_IN=""; BADTOK=""
+while IFS= read -r tok; do
+  [ -z "$tok" ] && continue
+  if [[ "$tok" =~ ^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ ]]; then
+    ID_IN="${ID_IN:+$ID_IN,}'$tok'"
+  elif [[ "$tok" =~ ^[^,\'\"[:space:]]+@[^,\'\"[:space:]]+$ ]]; then
+    USERNAME_IN="${USERNAME_IN:+$USERNAME_IN,}'$tok'"
+  else
+    BADTOK="$BADTOK '$tok'"
+  fi
+done <<< "$(printf '%s' "$AGENTS_CSV" | tr ',' '\n' | sed 's/^ *//;s/ *$//')"
+[ -z "$BADTOK" ] || emit_blocked "agent_members_csv contains token(s) that are neither a Username (...@...) nor a 15/18-char User Id (005...):$BADTOK"
+
+WHERE_PARTS=""
+[ -n "$USERNAME_IN" ] && WHERE_PARTS="Username IN ($USERNAME_IN)"
+[ -n "$ID_IN" ] && WHERE_PARTS="${WHERE_PARTS:+$WHERE_PARTS OR }Id IN ($ID_IN)"
+
+# Fail-closed with structured JSON: without `|| emit_blocked`, a non-zero query makes the command
+# substitution fail and set -e would exit before any blocked output. The jq -e guard separates a real
+# zero-result from an inconclusive/unparseable read so the two get distinct remediation.
+U_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, Username, Name FROM User WHERE ($WHERE_PARTS) AND IsActive=true" --json 2>/dev/null) \
+  || emit_blocked "Could not query User to resolve agent_members_csv (query failed: authentication, network, or API access). Re-run with a reachable org." "service-omni-agent-users-create"
+echo "$U_JSON" | jq -e '.result.totalSize | numbers' >/dev/null 2>&1 \
+  || emit_blocked "User resolution returned no parseable result (inconclusive). Re-run against a reachable org." "service-omni-agent-users-create"
+U_COUNT=$(echo "$U_JSON" | jq -r '.result.totalSize')
+[ "$U_COUNT" -gt 0 ] || emit_blocked "No ACTIVE users resolved from agent_members_csv. Verify the usernames/IDs are correct and the users are active." "service-omni-agent-users-create"
+
+USERS_JSON=$(echo "$U_JSON" | jq -c '[.result.records[] | {id:.Id, username:.Username, name:.Name}]')
+USER_IDS_IN=$(echo "$USERS_JSON" | jq -r '[.[].id] | map("'"'"'" + . + "'"'"'") | join(",")')
+
+# Step 3 - Ensure the Skill exists (reuse sObject; else deploy Skill metadata, then re-query)
+skill_id_by_name() {
+  sf data query --target-org "$ORG" --json \
+    --query "SELECT Id FROM Skill WHERE DeveloperName='$SKILL_DN'" 2>/dev/null \
+    | jq -r '.result.records[0].Id // ""' 2>/dev/null
+}
+SKILL_ID=$(skill_id_by_name)
+SKILL_STATE="reused"
+
+# PLAN_ONLY - report intent from read-only detection and stop before any write.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  if [ -n "$SKILL_ID" ]; then
+    emit_plan "action_needed" "Skill '$SKILL_DN' exists; would ensure a SkillUser binding for $U_COUNT active agent(s)."
+  else
+    emit_plan "action_needed" "Would deploy Skill '$SKILL_DN' and ensure a SkillUser binding for $U_COUNT active agent(s)."
+  fi
+fi
+
+if [ -z "$SKILL_ID" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  WORK="$(mktemp -d)"; trap 'rm -rf "$WORK" "$POST_ERR_FILE"' 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"
+  SKILL_DIR="$WORK/force-app/main/default/skills"; mkdir -p "$SKILL_DIR"
+  cat > "$SKILL_DIR/${SKILL_DN}.skill-meta.xml" <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<Skill xmlns="http://soap.sforce.com/2006/04/metadata">
+    <description>Created by service-omni-skills-based-routing-configure.</description>
+    <label>$(xml_escape "$SKILL_LABEL")</label>
+</Skill>
+XML
+  DEP_JSON=$(cd "$WORK" && sf project deploy start --target-org "$ORG" \
+    --metadata "Skill:${SKILL_DN}" --json 2>/dev/null || true)
+  DEP_OK=$(echo "$DEP_JSON" | jq -r '.result.success // false' 2>/dev/null || echo false)
+  if [ "$DEP_OK" != "true" ]; then
+    FAIL=$(echo "$DEP_JSON" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
+    [ -n "$FAIL" ] && [ "$FAIL" != "null" ] || FAIL=$(echo "$DEP_JSON" | jq -r '.message // "Unknown deploy error"' 2>/dev/null)
+    emit_blocked "Failed to deploy Skill '$SKILL_DN': $FAIL. Ensure skills-based routing is enabled in Omni-Channel settings." "service-omni-base-settings-configure"
+  fi
+  SKILL_ID=$(skill_id_by_name)
+  SKILL_STATE="created"
+  [ -n "$SKILL_ID" ] || emit_blocked "Deployed Skill '$SKILL_DN' but could not re-query its Id (org may still be indexing). Re-run to bind agents."
+fi
+
+# Step 4 - Ensure a SkillUser binding (SkillId, UserId) per active agent. This is the classic
+# Omni-Channel agent-skill model used by Setup > Skills > Assign Users. ServiceResourceSkill is a
+# Field Service model and cannot be used on a plain Service Cloud org where ServiceResource.IsActive
+# is unavailable.
+SU_JSON=$(sf data query --target-org "$ORG" --json \
+  --query "SELECT Id, UserId FROM SkillUser WHERE SkillId='$SKILL_ID' AND UserId IN ($USER_IDS_IN)" 2>/dev/null || echo '{}')
+EXISTING_SU=$(echo "$SU_JSON" | jq -c '[.result.records[]? | {user_id:.UserId, su_id:.Id}]' 2>/dev/null || echo '[]')
+
+AGENTS_OUT='[]'
+BIND_CREATED=0; BIND_REUSED=0
+PARTIAL_ERRORS=()
+
+# For each agent: ensure a SkillUser binding.
+while IFS= read -r row; do
+  [ -z "$row" ] && continue
+  USR_ID=$(echo "$row" | jq -r '.id')
+  UNAME=$(echo "$row" | jq -r '.username')
+
+  SU_ID=$(echo "$EXISTING_SU" | jq -r --arg u "$USR_ID" '.[] | select(.user_id==$u) | .su_id' | head -1)
+  BIND_STATE="reused"
+  if [ -z "$SU_ID" ] || [ "$SU_ID" = "null" ]; then
+    SU_ID=$(rest_post "SkillUser" "{\"SkillId\":\"$SKILL_ID\",\"UserId\":\"$USR_ID\"}")
+    if [ -z "$SU_ID" ]; then
+      ERR=$(post_err)
+      if printf '%s' "$ERR" | grep -q "DUPLICATE_VALUE"; then
+        BIND_STATE="reused"; BIND_REUSED=$((BIND_REUSED+1))
+        SU_ID=""
+      else
+        PARTIAL_ERRORS+=("$UNAME: skill binding failed - $ERR")
+        BIND_STATE="not_created"
+      fi
+    else
+      BIND_STATE="created"; BIND_CREATED=$((BIND_CREATED+1))
+    fi
+  else
+    BIND_REUSED=$((BIND_REUSED+1))
+  fi
+
+  SU_JQ='null'; [ -n "$SU_ID" ] && [ "$SU_ID" != "null" ] && SU_JQ=$(jq -n --arg s "$SU_ID" '$s')
+  AGENTS_OUT=$(echo "$AGENTS_OUT" | jq -c \
+    --arg u "$UNAME" --arg uid "$USR_ID" --argjson su "$SU_JQ" --arg bs "$BIND_STATE" \
+    '. + [{username:$u,user_id:$uid,skill_binding_id:$su,skill_binding_state:$bs}]')
+done < <(echo "$USERS_JSON" | jq -c '.[]')
+
+# Step 5 - Status + report
+if [ ${#PARTIAL_ERRORS[@]} -gt 0 ]; then
+  # Any success at all → partial; nothing succeeded → blocked.
+  if [ "$BIND_CREATED" -gt 0 ] || [ "$BIND_REUSED" -gt 0 ]; then
+    STATUS="partial"
+  else
+    STATUS="blocked"
+  fi
+  BLOCKING="Partial skills-based-routing configuration. Failures: ${PARTIAL_ERRORS[*]}"
+elif [ "$BIND_CREATED" -eq 0 ] && [ "$SKILL_STATE" = "reused" ]; then
+  STATUS="reused"; BLOCKING=""
+else
+  STATUS="configured"; BLOCKING=""
+fi
+
+BLOCKING_JQ='null'
+[ -n "$BLOCKING" ] && BLOCKING_JQ=$(jq -n --arg s "$BLOCKING" '$s')
+
+jq -n \
+  --arg status "$STATUS" \
+  --arg dn "$SKILL_DN" \
+  --arg sid "$SKILL_ID" \
+  --arg sstate "$SKILL_STATE" \
+  --argjson agents "$AGENTS_OUT" \
+  --argjson bind_created "$BIND_CREATED" \
+  --argjson bind_reused "$BIND_REUSED" \
+  --argjson blocking "$BLOCKING_JQ" \
+  '{
+    skill: "service-omni-skills-based-routing-configure",
+    status: $status,
+    skill_configured: {developer_name:$dn, id:$sid, state:$sstate},
+    agents: $agents,
+    created_counts: {skill_bindings:$bind_created},
+    reused_counts:  {skill_bindings:$bind_reused},
+    manual_actions: [],
+    blocking_issue: $blocking
+  }'

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

@@ -0,0 +1,120 @@
+"""Shared paths + fake-`sf` harness for the skills-based-routing contract suite.
+
+Drives ``configure-and-report.sh`` through ``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-skills-based-routing-configure"
+SCRIPT = f"{SKILL_DIR}/scripts/configure-and-report.sh"
+
+# PRODUCTION org - safe_to_write must refuse before any write.
+_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;;
+  "api request") echo '{"success":false,"errorCode":"FAKE_POST_SHOULD_NOT_BE_REACHED"}'; exit 0;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+# SANDBOX org. Tunables (all default to the "everything must be created" path):
+#   FAKE_SKILL_PRESENT=1 → the Skill already exists (reused); else absent → deploy then re-query.
+#   FAKE_BIND_PRESENT=1   → a SkillUser binding already exists for each user (reused); else create.
+#   FAKE_BIND_POST_FAIL=1 → the SkillUser POST fails for the second agent.
+#   FAKE_BIND_DUPLICATE=1 → the SkillUser POST returns DUPLICATE_VALUE and is reconciled as reused.
+# Two active users (005...0001 / 005...0002) are always resolved from the User query.
+_FAKE_SF_SANDBOX = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_PRESENT="${FAKE_SKILL_PRESENT:-0}"
+BIND_PRESENT="${FAKE_BIND_PRESENT:-0}"
+BIND_POST_FAIL="${FAKE_BIND_POST_FAIL:-0}"
+BIND_DUPLICATE="${FAKE_BIND_DUPLICATE:-0}"
+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 User"; then
+      echo '{"status":0,"result":{"records":[{"Id":"0050000000000001AAA","Username":"agent1@example.com","Name":"Agent One"},{"Id":"0050000000000002AAA","Username":"agent2@example.com","Name":"Agent Two"}],"totalSize":2}}'
+    elif printf '%s' "$args" | grep -q "FROM SkillUser"; then
+      if [ "$BIND_PRESENT" = "1" ]; then
+        echo '{"status":0,"result":{"records":[{"Id":"0C90000000000001AAA","UserId":"0050000000000001AAA"},{"Id":"0C90000000000002AAA","UserId":"0050000000000002AAA"}],"totalSize":2}}'
+      else echo '{"status":0,"result":{"records":[],"totalSize":0}}'; fi
+    elif printf '%s' "$args" | grep -q "FROM Skill"; then
+      if [ "$SKILL_PRESENT" = "1" ] || [ -f "$SELF_DIR/.skill_deployed" ]; then
+        echo '{"status":0,"result":{"records":[{"Id":"0PS0000000000001AAA"}],"totalSize":1}}'
+      else echo '{"status":0,"result":{"records":[],"totalSize":0}}'; fi
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+    exit 0;;
+  "project deploy")
+    touch "$SELF_DIR/.skill_deployed"
+    echo '{"status":0,"result":{"success":true,"files":[{"fullName":"'"$(printf '%s' "$args" | sed -n 's/.*Skill:\([A-Za-z0-9_]*\).*/\1/p')"'","type":"Skill","state":"Created"}]}}'
+    exit 0;;
+  "api request")
+    if printf '%s' "$args" | grep -q "sobjects/SkillUser"; then
+      if [ "$BIND_DUPLICATE" = "1" ]; then
+        echo '[{"errorCode":"DUPLICATE_VALUE","message":"duplicate value found: unique constraint (SkillId, UserId)"}]';
+      elif [ "$BIND_POST_FAIL" = "1" ] && printf '%s' "$args" | grep -q "0050000000000002AAA"; then
+        echo '[{"errorCode":"FIELD_CUSTOM_VALIDATION_EXCEPTION","message":"forced binding failure"}]';
+      else echo '{"success":true,"id":"0C90000000000009AAA"}'; fi
+    else
+      echo '{"success":true,"id":"000000000000000AAA"}'
+    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="sbr-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)