@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-supervisor-config-deploy/scripts/tests/_bootstrap.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SCRIPT = "service-omni-supervisor-config-deploy/scripts/deploy-and-report.sh"
+
+_FAKE_SF = r'''#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+state_dir="${FAKE_STATE_DIR:?}"
+deployed="$state_dir/deployed"
+actions="$state_dir/actions"
+tabs="$state_dir/tabs"
+trace="$state_dir/trace"
+capture_xml="$state_dir/deployed.xml"
+capture_package="$state_dir/package.xml"
+config_dn="${FAKE_CONFIG_DN:-Omni_Supervisor}"
+
+emit_surface() {
+  local kind="$1" source_file="$2" initial_json="$3" field="$4"
+  if [ ! -f "$deployed" ]; then
+    printf '%s' "$initial_json" | jq -c --arg field "$field" '
+      to_entries | {status:0,result:{records:map({($field):.value,DisplayOrder:(.key+1)})}}'
+    return
+  fi
+  if [ ! -s "$source_file" ]; then
+    echo '{"status":0,"result":{"records":[]}}'
+    return
+  fi
+  jq -R -s -c --arg field "$field" '
+    split("\n") | map(select(length>0)) | to_entries |
+    {status:0,result:{records:map({($field):.value,DisplayOrder:(.key+1)})}}' "$source_file"
+}
+
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}';;
+  "org list") echo '{"status":0,"result":[]}' ;;
+  "data query")
+    printf '%s\n' "$args" >> "$trace"
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+    elif printf '%s' "$args" | grep -q "FROM User"; then
+      echo '{"status":0,"result":{"records":[{"Id":"005xx0000000001AAA","Username":"supervisor1.0000000e@example.com","Profile":{"Name":"Standard User"}}]}}'
+    elif printf '%s' "$args" | grep -q "FROM Group"; then
+      echo '{"status":0,"result":{"records":[{"Id":"00Gxx0000000001AAA"}]}}'
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfigAction"; then
+      emit_surface action "$actions" "${FAKE_EXIST_ACTIONS:-[]}" OmniSupervisorActionType
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfigTab"; then
+      emit_surface tab "$tabs" "${FAKE_EXIST_TABS:-[]}" OmniSupervisorTabType
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfigUser"; then
+      echo '{"status":0,"result":{"records":[{"Id":"0Q4xx0000000001AAA"}]}}'
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfigQueue"; then
+      echo '{"status":0,"result":{"records":[{"Id":"0Q5xx0000000001AAA"}]}}'
+    elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfig"; then
+      printf '{"status":0,"result":{"records":[{"Id":"0Q2xx0000000001AAA","DeveloperName":"%s","MasterLabel":"%s","SkillVisibility":"%s"}]}}' "$config_dn" "${FAKE_MASTER_LABEL:-Existing Supervisor Label}" "${FAKE_SKILL_VISIBILITY:-AnySkill}"
+    else
+      echo '{"status":0,"result":{"records":[]}}'
+    fi;;
+  "project deploy")
+    if printf '%s' "$args" | grep -q " start "; then
+      cp "force-app/main/default/omniSupervisorConfigs/$config_dn.omniSupervisorConfig-meta.xml" "$capture_xml"
+      cp package.xml "$capture_package"
+      echo '{"status":0,"result":{"id":"0Afxx0000000001AAA"}}'
+    else
+      : > "$deployed"
+      if [ "${FAKE_DEPLOY_PRESERVES_SURFACE:-0}" = "1" ]; then
+        printf '%s' "${FAKE_EXIST_ACTIONS:-[]}" | jq -r '.[]' > "$actions"
+        printf '%s' "${FAKE_EXIST_TABS:-[]}" | jq -r '.[]' > "$tabs"
+      else
+        : > "$actions"; : > "$tabs"
+      fi
+      printf '{"status":0,"result":{"id":"0Afxx0000000001AAA","status":"Succeeded","files":[{"fullName":"%s","type":"OmniSupervisorConfig","state":"Changed"}]}}' "$config_dn"
+    fi;;
+  "data create")
+    printf '%s\n' "$args" >> "$trace"
+    if printf '%s' "$args" | grep -q "OmniSupervisorConfigAction"; then
+      value=$(printf '%s' "$args" | sed -n 's/.*OmniSupervisorActionType=\([^ ]*\).*/\1/p')
+      printf '%s\n' "$value" >> "$actions"
+    elif printf '%s' "$args" | grep -q "OmniSupervisorConfigTab"; then
+      value=$(printf '%s' "$args" | sed -n 's/.*OmniSupervisorTabType=\([^ ]*\).*/\1/p')
+      printf '%s\n' "$value" >> "$tabs"
+    fi
+    echo '{"status":0,"result":{"id":"0Q3xx0000000001AAA","success":true}}';;
+  *) echo '{"status":0,"result":{}}';;
+esac
+'''
+
+
+def last_json(output: str) -> dict:
+    decoder = json.JSONDecoder()
+    result, index = None, 0
+    while index < len(output):
+        if output[index] not in "{[":
+            index += 1
+            continue
+        try:
+            candidate, end = decoder.raw_decode(output, index)
+            if isinstance(candidate, dict):
+                result = candidate
+            index = end
+        except json.JSONDecodeError:
+            index += 1
+    assert result is not None, output
+    return result
+
+
+class FakeSf:
+    def __init__(self):
+        self.root: Path | None = None
+        self.bin_dir: Path | None = None
+        self.state_dir: Path | None = None
+
+    def __enter__(self):
+        self.root = Path(tempfile.mkdtemp(prefix="supconfig-fake-sf-"))
+        self.bin_dir = self.root / "bin"
+        self.state_dir = self.root / "state"
+        self.bin_dir.mkdir()
+        self.state_dir.mkdir()
+        executable = self.bin_dir / "sf"
+        executable.write_text(_FAKE_SF)
+        executable.chmod(0o755)
+        return self
+
+    def run(self, args, extra_env=None):
+        assert self.bin_dir is not None and self.state_dir is not None
+        env = dict(os.environ)
+        env["PATH"] = str(self.bin_dir) + os.pathsep + env.get("PATH", "")
+        env["FAKE_STATE_DIR"] = str(self.state_dir)
+        if extra_env:
+            env.update({key: str(value) for key, value 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 "")
+
+    def read_state(self, name: str) -> str:
+        assert self.state_dir is not None
+        path = self.state_dir / name
+        return path.read_text() if path.exists() else ""
+
+    def __exit__(self, *_):
+        import shutil
+        if self.root:
+            shutil.rmtree(self.root, ignore_errors=True)

package/skills/service-omni-supervisor-config-deploy/scripts/tests/test_supervisor_config_contracts.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import FakeSf, last_json  # noqa: E402
+
+
+class PreservationTests(unittest.TestCase):
+    def test_update_preserves_existing_surface_and_visibility(self):
+        actions = json.dumps(["AllAgents.ChangeQueues", "AllAgents.ChangeSkills"])
+        tabs = json.dumps(["Wallboard", "Agents"])
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "1", "CaseQueue"],
+                {
+                    "FAKE_EXIST_ACTIONS": actions,
+                    "FAKE_EXIST_TABS": tabs,
+                    "FAKE_SKILL_VISIBILITY": "AnySkill",
+                },
+            )
+            deployed_xml = fake.read_state("deployed.xml")
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 0, output)
+        self.assertIn("<skillVisibility>AnySkill</skillVisibility>", deployed_xml)
+        self.assertIn("OmniSupervisorActionType=AllAgents.ChangeQueues", trace)
+        self.assertIn("OmniSupervisorActionType=AllAgents.ChangeSkills", trace)
+        self.assertIn("OmniSupervisorTabType=Wallboard", trace)
+        self.assertIn("OmniSupervisorTabType=Agents", trace)
+        result = last_json(output)
+        self.assertEqual(result["skill_visibility"], "AnySkill", output)
+        self.assertEqual(result["surface_preservation"]["actions_restored"], 2, output)
+        self.assertEqual(result["surface_preservation"]["tabs_restored"], 2, output)
+
+    def test_explicit_visibility_overrides_existing_value(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "1", "CaseQueue", "", "AllSkills"],
+                {"FAKE_SKILL_VISIBILITY": "AnySkill"},
+            )
+            deployed_xml = fake.read_state("deployed.xml")
+
+        self.assertEqual(rc, 0, output)
+        self.assertIn("<skillVisibility>AllSkills</skillVisibility>", deployed_xml)
+        self.assertEqual(last_json(output)["skill_visibility"], "AllSkills", output)
+
+    def test_surface_rows_that_survive_deploy_are_not_inserted_again(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "1", "CaseQueue"],
+                {
+                    "FAKE_EXIST_ACTIONS": json.dumps(["AllAgents.ChangeQueues"]),
+                    "FAKE_EXIST_TABS": json.dumps(["Wallboard"]),
+                    "FAKE_DEPLOY_PRESERVES_SURFACE": "1",
+                },
+            )
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 0, output)
+        self.assertNotIn("data create", trace)
+        self.assertNotIn("OmniSupervisorActionType=", trace)
+        self.assertNotIn("OmniSupervisorTabType=", trace)
+        result = last_json(output)
+        self.assertEqual(result["surface_preservation"]["actions_restored"], 0, output)
+        self.assertEqual(result["surface_preservation"]["tabs_restored"], 0, output)
+
+    def test_unsupported_existing_surface_blocks_before_deploy(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "1", "CaseQueue"],
+                {"FAKE_EXIST_TABS": json.dumps(["FlexipageType"])},
+            )
+            deployed_xml = fake.read_state("deployed.xml")
+
+        self.assertEqual(rc, 1, output)
+        self.assertEqual(deployed_xml, "")
+        self.assertIn("cannot be safely restored", last_json(output)["blocking_issue"])
+
+    def test_custom_config_identifier_controls_query_manifest_and_deploy(self):
+        custom_config = "Regional_Supervisor"
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "1", "CaseQueue", "", "AnySkill", custom_config],
+                {
+                    "FAKE_CONFIG_DN": custom_config,
+                    "FAKE_MASTER_LABEL": "Regional Supervisor Team",
+                },
+            )
+            deployed_xml = fake.read_state("deployed.xml")
+            package_xml = fake.read_state("package.xml")
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 0, output)
+        self.assertEqual(last_json(output)["config_developer_name"], custom_config)
+        self.assertIn("<members>Regional_Supervisor</members>", package_xml)
+        self.assertIn("<masterLabel>Regional Supervisor Team</masterLabel>", deployed_xml)
+        self.assertIn("DeveloperName='Regional_Supervisor'", trace)
+        self.assertNotIn("DeveloperName='Omni_Supervisor'", trace)
+
+    def test_invalid_config_identifier_is_rejected_before_org_access(self):
+        with FakeSf() as fake:
+            rc, output = fake.run(
+                ["org", "1", "CaseQueue", "", "AnySkill", "Bad Config' OR Name != '"],
+            )
+            trace = fake.read_state("trace")
+
+        self.assertEqual(rc, 1, output)
+        self.assertIn("Invalid config_developer_name", output)
+        self.assertEqual(trace, "")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-supervisor-permset-assign/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: service-omni-supervisor-permset-assign
+description: "Use to assign the Salesforce-shipped standard ContactCenterSupervisor PermissionSet (default) to N existing supervisor users via PermissionSetAssignment DML. Idempotent — SOQL detects existing (user, perm-set) pairs before POST, and DUPLICATE_VALUE is treated as reused. The standard set carries its own permission-set license and assigns cleanly on Service-Cloud-enabled orgs; a user whose license lacks the entitlement surfaces FIELD_INTEGRITY_EXCEPTION so the operator can fix the profile/license. Triggers: assign the supervisor permset, grant supervisor perms, complete supervisor provisioning. Do not use on production orgs or to assign agent permsets."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-supervisor-config-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-supervisor-permset-assign
+
+Assign the Salesforce-shipped standard `ContactCenterSupervisor` PermissionSet to existing supervisor users via `PermissionSetAssignment`. The classic Omni-Channel Supervisor UI (Command Center) requires supervisors to hold contact-center supervisor permissions before `service-omni-supervisor-config-deploy` can bind them. The skill uses detect-before-POST idempotency and treats `DUPLICATE_VALUE` as an already-satisfied assignment.
+
+**Licensing.** The supervisor system permissions (`IsContactCenterSupervisor`, `OmniSupervisorManageQueue`, `ViewOmnichnlAnlytDshbrd`) are gated by a permission-set license. The standard `ContactCenterSupervisor` set carries its own license linkage and assigns cleanly on a Service-Cloud-enabled org, so it is the default and supported path — a hand-rolled custom set that re-declares these permissions fails with `FIELD_INTEGRITY_EXCEPTION`. If a specific user's license lacks the underlying entitlement, the assignment surfaces that same exception so the operator can move the user to a profile/license that carries it.
+
+That custom-permission-set warning does **not** mean assigning the existing Salesforce-shipped `ContactCenterSupervisor` set removes access or rewrites the set. This skill only creates a missing `PermissionSetAssignment`; it never creates, edits, or replaces the permission set itself.
+
+## Inputs
+
+```bash
+bash scripts/verify-and-assign.sh <org-alias> [count=1] [permission-set-names-csv=ContactCenterSupervisor]
+```
+
+- `org-alias` (required).
+- `count` (optional, default `1`, range `1..5`) — must match the supervisor user count.
+- `permission-set-names-csv` (optional, default `ContactCenterSupervisor`) — comma-separated for multiple. Every supervisor gets every listed set (cross-product).
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
+- The supervisor users exist and are active; fewer than `count` active users blocks with a remediation message.
+- The `ContactCenterSupervisor` set is Salesforce-shipped and present on any Service-Cloud-enabled org; a custom name that is missing blocks with a Setup click-path.
+- The executing user has `PermissionsAssignPermissionSets` (standard on System Administrator) — required even for org admins.
+- The three-way `safe_to_write` production guard applies — assigning permission sets on a production org can escalate a real user's privileges, so it blocks with no override.
+
+## Run
+
+`verify-and-assign.sh` performs the whole cycle:
+
+1. Compute `safe_to_write`; derive the 8-char org suffix.
+2. Validate every supplied permission-set name as a well-formed DeveloperName (SOQL-injection guard) before any `sf` call.
+3. Resolve the `supervisor{1..N}.<suffix>@example.com` users, filtered to `IsActive=true`; block if fewer than `count` are active (an inactive occupant does not satisfy the count).
+4. Resolve each `PermissionSet` by name; block naming which is missing.
+5. Query existing `PermissionSetAssignment` for the (user × set) cross-product; compute the missing pairs.
+6. POST one assignment per missing pair (individual POSTs, no `allOrNone`); treat `DUPLICATE_VALUE` as reused.
+7. Re-query to confirm final state and emit the report.
+
+## Behavior
+
+**Cross-product.** Every supervisor gets every listed set; a partial assignment is a failure, not a feature.
+
+**Idempotency.** `PermissionSetAssignment` has a uniqueness constraint on (AssigneeId, PermissionSetId), so a re-POST raises `DUPLICATE_VALUE`; the skill detects existing pairs first and treats that as reused for concurrent-run safety. POSTs are individual so one error never rolls back its siblings, and it re-queries after all POSTs — a 201 only means the write was accepted; a SOQL confirms it is active.
+
+**Non-destructive.** Create-only; it never deletes existing assignments (supervisors may hold out-of-band permissions) and derives users from the supervisor pattern rather than an explicit id list.
+
+## Output contract
+
+A single JSON object with `status` ∈ `assigned` | `reused` | `partial` | `blocked`, the resolved `permission_sets`, `org_suffix`, `requested_count`, `expected_assignment_count` (= `requested_count × len(permission_sets)`), a `before` snapshot, `assigned_this_run`/`assigned_count`, `reused_count`, an `after` snapshot, `manual_actions`, and `blocking_issue`.
+
+- `assigned` — at least one new assignment created; all expected pairs exist after.
+- `reused` — all expected pairs already existed; nothing POSTed.
+- `partial` — some POSTs failed; final count is below expected.
+- `blocked` — precondition failed (production org, missing set, missing/inactive users, or a license that does not allow the permission).
+
+`assigned_count + reused_count == expected_assignment_count` unless `partial`; `blocking_issue` is non-null only for `blocked`/`partial`.
+
+## Limitations
+
+- Provisioning the user license that the supervisor permset requires is the users-create skill's responsibility, not this one.
+- Assigns individual PermissionSets only — a `PermissionSetGroup` is a different sObject and is out of scope.
+- Create-only; it does not remove assignments.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | Before the POST loop — PermissionSetAssignment schema, `DUPLICATE_VALUE` semantics, and why users are derived from the supervisor pattern rather than an explicit id list |

package/skills/service-omni-supervisor-permset-assign/references/api-notes.md

@@ -0,0 +1,48 @@
+# service-omni-supervisor-permset-assign — API notes
+
+Load this reference **only when POSTs fail or you need to add new PermissionSets to the skill**. Under normal operation `verify-and-assign.sh` just runs and emits its JSON.
+
+## Why REST POST over Metadata deploy
+
+`PermissionSetAssignment` is a **Data API sObject only** — no Metadata API surface. You cannot deploy assignments via `.permissionSetAssignment-meta.xml`. The DML approach with detect-before-POST loops is the only headless option.
+
+Contrast with the parent `PermissionSet` itself, which **does** have a Metadata surface (deployable via `.permissionset-meta.xml`). That's why v1.2 has a separate `service-omni-supervisor-permset-metadata-deploy` skill to ship the permset itself; this skill just assigns it.
+
+## Idempotency contract
+
+`PermissionSetAssignment` has a Salesforce-enforced uniqueness constraint on `(AssigneeId, PermissionSetId)`. Duplicate POSTs return `DUPLICATE_VALUE` errors.
+
+The skill handles this two ways:
+
+1. **Pre-detect via SOQL** — query existing pairs before POSTing; skip already-existing pairs. Avoids most `DUPLICATE_VALUE` responses.
+2. **Concurrent-run safe** — if another agent (or admin) assigns the same permset between our detect and POST, treat `DUPLICATE_VALUE` as reused (do NOT increment `assigned_count`). No error surfaced.
+
+Re-runs on an already-configured org return `status: reused` with `assigned_count: 0` and `before.existing_count == after.assignment_count == expected_assignment_count`.
+
+## Default permset: standard ContactCenterSupervisor (not a custom permset)
+
+This skill defaults to the Salesforce-shipped **standard `ContactCenterSupervisor`** PermissionSet, which is present on any Service-Cloud-enabled org and assigns cleanly to a user on a **Salesforce user license** with the **Service Cloud feature** (`UserPermissionsSupportUser=true`).
+
+**Why not a custom `Omni_Supervisor` permset?** A custom permset that re-declares the supervisor system permissions (`IsContactCenterSupervisor`, `OmniSupervisorManageQueue`, `ViewOmnichnlAnlytDshbrd`) is rejected with `FIELD_INTEGRITY_EXCEPTION — The user license doesn't allow the permission: IsContactCenterSupervisor`, because those permissions are gated by a permission-set license the custom set does not carry. The standard `ContactCenterSupervisor` permset carries its own license linkage and grants `IsContactCenterSupervisor` cleanly — so it is the only supported path. This skill assigns permsets that already exist on the org; it does not ship or deploy a custom supervisor permset.
+
+## Post-run SOQL verification
+
+```sql
+SELECT AssigneeId, PermissionSetId, Assignee.Username, PermissionSet.Name
+FROM PermissionSetAssignment
+WHERE PermissionSet.Name='ContactCenterSupervisor'
+  AND Assignee.Username LIKE 'supervisor%.%'
+```
+
+Expected: N rows, where N = `count` param.
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `blocked: Expected PermissionSets [ContactCenterSupervisor]; found []` | Standard permset name not found (unusual — it ships with Service Cloud) | Confirm Service Cloud is enabled on the org |
+| `blocked: Expected N supervisor users ...; found M` | Supervisor users not created or inactive | Provision or reactivate the missing users, then rerun |
+| `DUPLICATE_VALUE` in POST results | Concurrent admin assigned same pair | Treated as reused, no action needed |
+| `FIELD_INTEGRITY_EXCEPTION — The user license doesn't allow the permission: IsContactCenterSupervisor` | Supervisor user is on a license that doesn't carry the contact-center supervisor entitlement | Move the user to a profile/license that carries the entitlement, then rerun |
+| `INSUFFICIENT_ACCESS_OR_READONLY` on POST | SF CLI user lacks ManageUsers perm | Ensure authenticated user is System Administrator |
+| `INSUFFICIENT_ACCESS_OR_READONLY` on POST | SF CLI user lacks ManageUsers perm | Ensure authenticated user is System Administrator |