@salesforce/afv-skills 1.56.0 → 1.58.0

package/skills/service-omni-command-center-configure/scripts/configure-and-report.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+# Configure Command Center for Service V2 through a preserved OmniChannel Settings document.
+
+set -euo pipefail
+
+usage() {
+  echo '{"status":"blocked","reason_code":"invalid_arguments","blocking_issue":"Usage: bash configure-and-report.sh <plan|run> <org-alias> [--apply] [--conversation-monitoring true|false] [--agent-sneak-peek true|false] [--customer-sneak-peek true|false] [--whisper-messaging true|false] [--queues-and-skills true|false]"}' >&2
+  exit 1
+}
+
+[ "$#" -ge 2 ] || usage
+
+MODE="$1"
+ORG="$2"
+shift 2
+
+case "$MODE" in
+  plan|run) ;;
+  *) usage ;;
+esac
+
+APPLY=false
+REQUESTED_JSON='{"enableCommandCenterForServiceV2":true}'
+ASSIGNMENTS=("enableCommandCenterForServiceV2=true")
+
+add_setting() {
+  local metadata_name="$1"
+  local value="$2"
+  if [ "$value" != "true" ] && [ "$value" != "false" ]; then
+    jq -n --arg name "$metadata_name" --arg value "$value" \
+      '{status:"blocked",reason_code:"invalid_arguments",blocking_issue:("Expected true or false for " + $name + ", received: " + $value)}' >&2
+    exit 1
+  fi
+  REQUESTED_JSON=$(jq -c --arg name "$metadata_name" --argjson value "$value" '. + {($name):$value}' <<<"$REQUESTED_JSON")
+  ASSIGNMENTS+=("$metadata_name=$value")
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --apply)
+      APPLY=true
+      shift
+      ;;
+    --conversation-monitoring|--agent-sneak-peek|--customer-sneak-peek|--whisper-messaging|--queues-and-skills)
+      [ "$#" -ge 2 ] || usage
+      case "$1" in
+        --conversation-monitoring) FIELD="enableConversationMonitoring" ;;
+        --agent-sneak-peek) FIELD="enableAgentSneakPeek" ;;
+        --customer-sneak-peek) FIELD="enableClientSneakPeek" ;;
+        --whisper-messaging) FIELD="enableWhisperMessaging" ;;
+        --queues-and-skills) FIELD="enableSkillsAndQueueActions" ;;
+      esac
+      add_setting "$FIELD" "$2"
+      shift 2
+      ;;
+    *) usage ;;
+  esac
+done
+
+if [ "$MODE" = "plan" ] && [ "$APPLY" = "true" ]; then
+  jq -n '{status:"blocked",reason_code:"invalid_arguments",blocking_issue:"--apply is not valid in plan mode."}' >&2
+  exit 1
+fi
+
+if [ "$MODE" = "run" ] && [ "$APPLY" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"apply_required",requested:$requested,safe_to_write:null,deploy_id:null,blocking_issue:"run mode requires explicit --apply consent; no org changes were made."}'
+  exit 1
+fi
+
+for dependency in sf jq python3; do
+  if ! command -v "$dependency" >/dev/null 2>&1; then
+    jq -n --arg dependency "$dependency" \
+      '{status:"blocked",reason_code:"missing_dependency",blocking_issue:("Required command is unavailable: " + $dependency)}' >&2
+    exit 1
+  fi
+done
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  jq -n --arg org "$ORG" \
+    '{status:"blocked",reason_code:"org_not_authenticated",blocking_issue:("Org alias is not authenticated: " + $org)}' >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DOCUMENT_TOOL="$SCRIPT_DIR/settings_document.py"
+WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/omni-command-center-configure.XXXXXX")"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+create_project() {
+  local directory="$1"
+  mkdir -p "$directory/force-app/main/default"
+  printf '%s\n' '{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"66.0"}' > "$directory/sfdx-project.json"
+}
+
+retrieve_settings() {
+  local directory="$1"
+  create_project "$directory"
+  (cd "$directory" && sf project retrieve start --target-org "$ORG" --metadata "Settings:OmniChannel" --json >/dev/null 2>&1)
+}
+
+settings_path() {
+  printf '%s/force-app/main/default/settings/OmniChannel.settings-meta.xml' "$1"
+}
+
+if ! retrieve_settings "$WORK_DIR/before"; then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"retrieve_failed",requested:$requested,blocking_issue:"Could not retrieve Settings:OmniChannel. Verify org access and retry."}'
+  exit 1
+fi
+
+BEFORE_XML="$(settings_path "$WORK_DIR/before")"
+if [ ! -f "$BEFORE_XML" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"retrieve_failed",requested:$requested,blocking_issue:"The retrieve completed without an OmniChannel settings document."}'
+  exit 1
+fi
+
+if ! BEFORE_JSON=$(python3 "$DOCUMENT_TOOL" inspect "$BEFORE_XML" 2>/dev/null); then
+  jq -n --argjson requested "$REQUESTED_JSON" \
+    '{status:"blocked",reason_code:"invalid_settings_document",requested:$requested,blocking_issue:"The retrieved OmniChannel settings document could not be parsed."}'
+  exit 1
+fi
+
+API_PRESENT=$(jq -r '.settings.enableCommandCenterForServiceV2.present' <<<"$BEFORE_JSON")
+if [ "$API_PRESENT" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"platform_api_unavailable",requested:$requested,before:$before,after:null,safe_to_write:null,deploy_id:null,verification:null,manual_actions:[{id:"WAIT_FOR_W_24039822",title:"Use a target release containing the W-24039822 Metadata API contract (Core PR #16874)."}],blocking_issue:"The target org does not expose enableCommandCenterForServiceV2 in Settings:OmniChannel; no deployment was attempted."}'
+  exit 1
+fi
+
+values_match() {
+  local snapshot="$1"
+  jq -ne --argjson requested "$REQUESTED_JSON" --argjson snapshot "$snapshot" '
+    all($requested | to_entries[];
+      (.key as $name | .value as $wanted |
+        $snapshot.settings[$name].present == true and $snapshot.settings[$name].value == $wanted)
+    )
+  ' >/dev/null
+}
+
+query_verification() {
+  local seed_json tab_json seed tab
+  seed_json=$(sf data query --target-org "$ORG" --use-tooling-api --json \
+    --query "SELECT Id FROM FlexiPage WHERE DeveloperName='CommandCenterForServiceV2_L'" 2>/dev/null || true)
+  if [ "$(jq -r '.status // 1' <<<"$seed_json" 2>/dev/null)" = "0" ]; then
+    if [ "$(jq -r '.result.totalSize // 0' <<<"$seed_json")" -gt 0 ]; then seed=true; else seed=false; fi
+  else
+    seed=unknown
+  fi
+
+  tab_json=$(sf data query --target-org "$ORG" --json \
+    --query "SELECT Name FROM TabDefinition WHERE Name='standard-commandcenterforservicev2' LIMIT 1" 2>/dev/null || true)
+  if [ "$(jq -r '.status // 1' <<<"$tab_json" 2>/dev/null)" = "0" ]; then
+    if [ "$(jq -r '.result.totalSize // 0' <<<"$tab_json")" -gt 0 ]; then tab=true; else tab=false; fi
+  else
+    tab=unknown
+  fi
+
+  jq -n --arg seed "$seed" --arg tab "$tab" \
+    '{seed_flexipage_present:$seed,v2_tab_present:$tab,complete:($seed == "true" and $tab == "true")}'
+}
+
+BEFORE_MATCH=false
+if values_match "$BEFORE_JSON"; then BEFORE_MATCH=true; fi
+
+if [ "$BEFORE_MATCH" = "true" ]; then
+  VERIFY_JSON=$(query_verification)
+  if [ "$(jq -r '.complete' <<<"$VERIFY_JSON")" != "true" ]; then
+    jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson verification "$VERIFY_JSON" \
+      '{status:"blocked",reason_code:"seed_incomplete",requested:$requested,before:$before,after:$before,safe_to_write:null,deploy_id:null,verification:$verification,manual_actions:[{id:"REPAIR_V2_SEED",title:"The V2 preference is already enabled but its page or tab cannot be proven. Diagnose the platform seed before retrying; this skill will not force an OFF-to-ON cycle."}],blocking_issue:"Command Center V2 is enabled but its seed artifacts are missing or unreadable."}'
+    exit 1
+  fi
+
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson verification "$VERIFY_JSON" \
+    '{status:"reused",reason_code:"already_configured",requested:$requested,before:$before,after:$before,safe_to_write:null,deploy_id:null,verification:$verification,manual_actions:[{id:"ASSIGN_V2_PERMISSION",title:"Assign CommandCenterForServiceUser to each intended supervisor, then verify with service-omni-command-center-analyze."}],blocking_issue:null}'
+  exit 0
+fi
+
+if [ "$MODE" = "plan" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"action_needed",reason_code:"changes_required",requested:$requested,before:$before,after:null,safe_to_write:null,deploy_id:null,verification:null,manual_actions:[],blocking_issue:null}'
+  exit 0
+fi
+
+ORG_GUARD_JSON=$(sf data query --target-org "$ORG" --json \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" 2>/dev/null || true)
+if [ "$(jq -r '.status // 1' <<<"$ORG_GUARD_JSON" 2>/dev/null)" != "0" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"guard_query_failed",requested:$requested,before:$before,safe_to_write:null,deploy_id:null,blocking_issue:"Could not evaluate the non-production safe_to_write guard."}'
+  exit 1
+fi
+
+IS_SANDBOX=$(jq -r '.result.records[0].IsSandbox' <<<"$ORG_GUARD_JSON")
+TRIAL_EXP=$(jq -r '.result.records[0].TrialExpirationDate // "null"' <<<"$ORG_GUARD_JSON")
+ORG_TYPE=$(jq -r '.result.records[0].OrganizationType // ""' <<<"$ORG_GUARD_JSON")
+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
+
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"unsafe_target",requested:$requested,before:$before,safe_to_write:false,deploy_id:null,blocking_issue:"Refusing to configure Command Center V2 in a production customer org."}'
+  exit 1
+fi
+
+create_project "$WORK_DIR/deploy"
+DEPLOY_XML="$(settings_path "$WORK_DIR/deploy")"
+if ! python3 "$DOCUMENT_TOOL" render "$BEFORE_XML" "$DEPLOY_XML" "${ASSIGNMENTS[@]}" >/dev/null; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" \
+    '{status:"blocked",reason_code:"render_failed",requested:$requested,before:$before,safe_to_write:true,deploy_id:null,blocking_issue:"Could not construct the preserved OmniChannel settings document."}'
+  exit 1
+fi
+
+DEPLOY_JSON=$(cd "$WORK_DIR/deploy" && sf project deploy start --target-org "$ORG" --source-dir "$DEPLOY_XML" --json 2>/dev/null || true)
+DEPLOY_SUCCESS=$(jq -r '.result.success // false' <<<"$DEPLOY_JSON" 2>/dev/null)
+DEPLOY_STATUS=$(jq -r '.result.status // ""' <<<"$DEPLOY_JSON" 2>/dev/null)
+DEPLOY_ID=$(jq -r '.result.id // ""' <<<"$DEPLOY_JSON" 2>/dev/null)
+if [ "$DEPLOY_SUCCESS" != "true" ] || [ "$DEPLOY_STATUS" = "SucceededPartial" ]; then
+  DEPLOY_ERROR=$(jq -r '.result.details.componentFailures // [] | if type == "array" then map(.problem) | join("; ") else .problem // "" end' <<<"$DEPLOY_JSON" 2>/dev/null)
+  if [ -z "$DEPLOY_ERROR" ] || [ "$DEPLOY_ERROR" = "null" ]; then
+    DEPLOY_ERROR=$(jq -r '.message // .result.errorMessage // "Unknown deploy error"' <<<"$DEPLOY_JSON" 2>/dev/null)
+  fi
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --arg id "$DEPLOY_ID" --arg error "$DEPLOY_ERROR" \
+    '{status:"blocked",reason_code:"deploy_failed",requested:$requested,before:$before,after:null,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:("OmniChannel settings deployment failed: " + $error)}'
+  exit 1
+fi
+
+if ! retrieve_settings "$WORK_DIR/after"; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"verification_failed",requested:$requested,before:$before,after:null,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:"Deployment succeeded, but post-deploy Settings:OmniChannel retrieval failed."}'
+  exit 1
+fi
+
+AFTER_XML="$(settings_path "$WORK_DIR/after")"
+if [ ! -f "$AFTER_XML" ] || ! AFTER_JSON=$(python3 "$DOCUMENT_TOOL" inspect "$AFTER_XML" 2>/dev/null); then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"verification_failed",requested:$requested,before:$before,after:null,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:"Deployment succeeded, but the post-deploy settings document could not be inspected."}'
+  exit 1
+fi
+
+if ! values_match "$AFTER_JSON"; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"verification_failed",requested:$requested,before:$before,after:$after,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:null,blocking_issue:"Deployment reported success, but one or more requested settings did not persist."}'
+  exit 1
+fi
+
+VERIFY_JSON=$(query_verification)
+if [ "$(jq -r '.complete' <<<"$VERIFY_JSON")" != "true" ]; then
+  jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --argjson verification "$VERIFY_JSON" --arg id "$DEPLOY_ID" \
+    '{status:"blocked",reason_code:"seed_incomplete",requested:$requested,before:$before,after:$after,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:$verification,manual_actions:[{id:"INSPECT_V2_SEED",title:"The settings persisted, but the V2 page and tab were not both observable. Inspect the platform seed hook before claiming readiness."}],blocking_issue:"Command Center V2 settings persisted, but seed verification is incomplete."}'
+  exit 1
+fi
+
+jq -n --argjson requested "$REQUESTED_JSON" --argjson before "$BEFORE_JSON" --argjson after "$AFTER_JSON" --argjson verification "$VERIFY_JSON" --arg id "$DEPLOY_ID" \
+  '{status:"configured",reason_code:"configured_and_verified",requested:$requested,before:$before,after:$after,safe_to_write:true,deploy_id:(if $id == "" then null else $id end),verification:$verification,manual_actions:[{id:"ASSIGN_V2_PERMISSION",title:"Assign CommandCenterForServiceUser to each intended supervisor, then verify with service-omni-command-center-analyze."}],blocking_issue:null}'

package/skills/service-omni-command-center-configure/scripts/settings_document.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Inspect or safely mutate a retrieved OmniChannel Settings document."""
+
+import argparse
+import json
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+
+METADATA_NS = "http://soap.sforce.com/2006/04/metadata"
+FIELDS = (
+    "enableCommandCenterForServiceV2",
+    "enableConversationMonitoring",
+    "enableAgentSneakPeek",
+    "enableClientSneakPeek",
+    "enableWhisperMessaging",
+    "enableSkillsAndQueueActions",
+)
+
+
+def parse_document(path: Path) -> Tuple[ET.ElementTree, ET.Element]:
+    tree = ET.parse(path)
+    return tree, tree.getroot()
+
+
+def find_element(root: ET.Element, name: str) -> Optional[ET.Element]:
+    return root.find(f"{{{METADATA_NS}}}{name}")
+
+
+def inspect(path: Path) -> int:
+    _, root = parse_document(path)
+    settings = {}
+    for name in FIELDS:
+        element = find_element(root, name)
+        text = (element.text or "").strip().lower() if element is not None else ""
+        settings[name] = {
+            "present": element is not None,
+            "value": text == "true" if text in {"true", "false"} else None,
+        }
+    print(json.dumps({"settings": settings}, separators=(",", ":")))
+    return 0
+
+
+def render(source: Path, destination: Path, assignments: List[str]) -> int:
+    tree, root = parse_document(source)
+    requested = {}
+    for assignment in assignments:
+        if "=" not in assignment:
+            raise ValueError(f"Invalid assignment: {assignment}")
+        name, value = assignment.split("=", 1)
+        if name not in FIELDS:
+            raise ValueError(f"Unsupported setting: {name}")
+        if value not in {"true", "false"}:
+            raise ValueError(f"Invalid boolean for {name}: {value}")
+        requested[name] = value
+
+    if "enableCommandCenterForServiceV2" not in requested:
+        raise ValueError("enableCommandCenterForServiceV2 must be requested")
+
+    for name, value in requested.items():
+        element = find_element(root, name)
+        if element is None:
+            element = ET.SubElement(root, f"{{{METADATA_NS}}}{name}")
+        element.text = value
+
+    ET.register_namespace("", METADATA_NS)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    tree.write(destination, encoding="UTF-8", xml_declaration=True)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(dest="operation", required=True)
+
+    inspect_parser = subparsers.add_parser("inspect")
+    inspect_parser.add_argument("path", type=Path)
+
+    render_parser = subparsers.add_parser("render")
+    render_parser.add_argument("source", type=Path)
+    render_parser.add_argument("destination", type=Path)
+    render_parser.add_argument("assignments", nargs="+")
+
+    args = parser.parse_args()
+    try:
+        if args.operation == "inspect":
+            return inspect(args.path)
+        return render(args.source, args.destination, args.assignments)
+    except (ET.ParseError, OSError, ValueError) as error:
+        print(json.dumps({"error": str(error)}, separators=(",", ":")), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/service-omni-command-center-configure/scripts/tests/test_command_center_configure_contracts.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SCRIPT = SKILLS_ROOT / "service-omni-command-center-configure/scripts/configure-and-report.sh"
+DOCUMENT_TOOL = SKILLS_ROOT / "service-omni-command-center-configure/scripts/settings_document.py"
+
+
+FAKE_SF = r"""#!/usr/bin/env bash
+set -euo pipefail
+args="$*"
+[ -z "${FAKE_CALL_LOG:-}" ] || printf '%s\n' "$args" >> "$FAKE_CALL_LOG"
+
+if [ "${1:-} ${2:-}" = "org display" ]; then
+  echo '{"status":0,"result":{"username":"fake@example.invalid"}}'
+  exit 0
+fi
+
+if [ "${1:-} ${2:-}" = "project retrieve" ]; then
+  mkdir -p force-app/main/default/settings
+  target=force-app/main/default/settings/OmniChannel.settings-meta.xml
+  if [ -f "$FAKE_STATE_DIR/deployed.xml" ]; then
+    cp "$FAKE_STATE_DIR/deployed.xml" "$target"
+  else
+    {
+      echo '<?xml version="1.0" encoding="UTF-8"?>'
+      echo '<OmniChannelSettings xmlns="http://soap.sforce.com/2006/04/metadata">'
+      echo '  <enableOmniChannel>true</enableOmniChannel>'
+      echo '  <unrelatedSetting>true</unrelatedSetting>'
+      if [ "${FAKE_API_PRESENT:-1}" = "1" ]; then
+        echo "  <enableCommandCenterForServiceV2>${FAKE_V2:-false}</enableCommandCenterForServiceV2>"
+        echo "  <enableConversationMonitoring>${FAKE_CONVERSATION:-false}</enableConversationMonitoring>"
+        echo "  <enableAgentSneakPeek>${FAKE_AGENT_PEEK:-false}</enableAgentSneakPeek>"
+        echo "  <enableClientSneakPeek>${FAKE_CLIENT_PEEK:-false}</enableClientSneakPeek>"
+        echo "  <enableWhisperMessaging>${FAKE_WHISPER:-false}</enableWhisperMessaging>"
+        echo "  <enableSkillsAndQueueActions>${FAKE_QUEUE_ACTIONS:-false}</enableSkillsAndQueueActions>"
+      fi
+      echo '</OmniChannelSettings>'
+    } > "$target"
+  fi
+  echo '{"status":0,"result":{"success":true}}'
+  exit 0
+fi
+
+if [ "${1:-} ${2:-}" = "project deploy" ]; then
+  if [ "${FAKE_DEPLOY_FAIL:-0}" = "1" ]; then
+    echo '{"status":1,"message":"simulated failure","result":{"success":false,"status":"Failed"}}'
+    exit 1
+  fi
+  source_path=""
+  while [ "$#" -gt 0 ]; do
+    if [ "$1" = "--source-dir" ]; then source_path="$2"; break; fi
+    shift
+  done
+  cp "$source_path" "$FAKE_STATE_DIR/deployed.xml"
+  touch "$FAKE_STATE_DIR/deployed"
+  echo '{"status":0,"result":{"success":true,"status":"Succeeded","id":"0AfFakeDeploy"}}'
+  exit 0
+fi
+
+if [ "${1:-} ${2:-}" = "data query" ]; then
+  if printf '%s' "$args" | grep -q 'FROM Organization'; then
+    if [ "${FAKE_PRODUCTION:-0}" = "1" ]; then
+      echo '{"status":0,"result":{"records":[{"IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}]}}'
+    else
+      echo '{"status":0,"result":{"records":[{"IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
+    fi
+  elif printf '%s' "$args" | grep -q 'FROM FlexiPage'; then
+    if { [ -f "$FAKE_STATE_DIR/deployed" ] && [ "${FAKE_SEED_AFTER_DEPLOY:-1}" = "1" ]; } || [ "${FAKE_SEED_PRESENT:-0}" = "1" ]; then
+      echo '{"status":0,"result":{"records":[{"Id":"0M0Fake"}],"totalSize":1}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+  elif printf '%s' "$args" | grep -q 'FROM TabDefinition'; then
+    if { [ -f "$FAKE_STATE_DIR/deployed" ] && [ "${FAKE_TAB_AFTER_DEPLOY:-1}" = "1" ]; } || [ "${FAKE_TAB_PRESENT:-0}" = "1" ]; then
+      echo '{"status":0,"result":{"records":[{"Name":"standard-commandcenterforservicev2"}],"totalSize":1}}'
+    else
+      echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+    fi
+  else
+    echo '{"status":0,"result":{"records":[],"totalSize":0}}'
+  fi
+  exit 0
+fi
+
+echo '{"status":1,"message":"unexpected fake sf invocation"}'
+exit 1
+"""
+
+
+def run_script(*args: str, **environment: str):
+    with tempfile.TemporaryDirectory(prefix="command-center-configure-") as directory:
+        root = Path(directory)
+        sf = root / "sf"
+        sf.write_text(FAKE_SF)
+        sf.chmod(0o755)
+        state = root / "state"
+        state.mkdir()
+        call_log = root / "calls.log"
+        env = dict(os.environ)
+        env.update(environment)
+        env["FAKE_STATE_DIR"] = str(state)
+        env["FAKE_CALL_LOG"] = str(call_log)
+        env["PATH"] = str(root) + os.pathsep + env.get("PATH", "")
+        result = subprocess.run(
+            ["bash", str(SCRIPT), *args],
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=str(SKILLS_ROOT),
+        )
+        calls = call_log.read_text() if call_log.exists() else ""
+        deployed = (state / "deployed.xml").read_text() if (state / "deployed.xml").exists() else ""
+        return result, calls, deployed
+
+
+class CommandCenterConfigureContracts(unittest.TestCase):
+    def test_script_and_python_syntax(self):
+        shell = subprocess.run(["bash", "-n", str(SCRIPT)], capture_output=True, text=True)
+        self.assertEqual(shell.returncode, 0, shell.stderr)
+        compile_result = subprocess.run(
+            ["python3", "-c", f"import ast, pathlib; ast.parse(pathlib.Path({str(DOCUMENT_TOOL)!r}).read_text())"],
+            capture_output=True,
+            text=True,
+            env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+        )
+        self.assertEqual(compile_result.returncode, 0, compile_result.stderr)
+
+    def test_run_requires_apply_before_any_sf_call(self):
+        result, calls, _ = run_script("run", "test-org")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["reason_code"], "apply_required")
+        self.assertEqual(calls, "")
+
+    def test_plan_reports_changes_without_deploying(self):
+        result, calls, _ = run_script("plan", "test-org")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout)["status"], "action_needed")
+        self.assertNotIn("project deploy", calls)
+
+    def test_missing_platform_field_fails_before_deploy(self):
+        result, calls, _ = run_script("run", "test-org", "--apply", FAKE_API_PRESENT="0")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["reason_code"], "platform_api_unavailable")
+        self.assertNotIn("project deploy", calls)
+
+    def test_production_org_is_refused(self):
+        result, calls, _ = run_script("run", "test-org", "--apply", FAKE_PRODUCTION="1")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["reason_code"], "unsafe_target")
+        self.assertNotIn("project deploy", calls)
+
+    def test_run_preserves_unrelated_and_unspecified_settings(self):
+        result, calls, deployed = run_script(
+            "run",
+            "test-org",
+            "--apply",
+            "--agent-sneak-peek",
+            "true",
+        )
+        payload = json.loads(result.stdout)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(payload["status"], "configured")
+        self.assertIn("project deploy", calls)
+        self.assertIn("<unrelatedSetting>true</unrelatedSetting>", deployed)
+        self.assertIn("<enableConversationMonitoring>false</enableConversationMonitoring>", deployed)
+        self.assertIn("<enableAgentSneakPeek>true</enableAgentSneakPeek>", deployed)
+        self.assertIn("<enableCommandCenterForServiceV2>true</enableCommandCenterForServiceV2>", deployed)
+
+    def test_already_ready_is_reused_without_deploy(self):
+        result, calls, _ = run_script(
+            "run",
+            "test-org",
+            "--apply",
+            FAKE_V2="true",
+            FAKE_SEED_PRESENT="1",
+            FAKE_TAB_PRESENT="1",
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout)["status"], "reused")
+        self.assertNotIn("project deploy", calls)
+
+    def test_persisted_settings_without_seed_are_blocked(self):
+        result, _, _ = run_script(
+            "run",
+            "test-org",
+            "--apply",
+            FAKE_SEED_AFTER_DEPLOY="0",
+            FAKE_TAB_AFTER_DEPLOY="0",
+        )
+        self.assertEqual(result.returncode, 1)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["reason_code"], "seed_incomplete")
+        self.assertEqual(payload["after"]["settings"]["enableCommandCenterForServiceV2"]["value"], True)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)