@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-supervisor-users-create/references/apex-patterns.md

@@ -0,0 +1,73 @@
+# service-omni-supervisor-users-create — Apex patterns
+
+Load this reference **only when the Apex template needs modification or debugging**. Under normal operation `run-create.sh` handles everything.
+
+## Why Anonymous Apex over REST User POST
+
+Two forcing constraints:
+
+
+1. **`System.setPassword()` is Apex-only.** REST POST creates the user but requires an email-based password reset flow. That's a UX blocker for bootstrap scenarios.
+2. **In-transaction re-check for concurrency.** If two operators run this skill simultaneously against the same org, REST POSTs race and one hits `DUPLICATE_USERNAME`. Apex re-queries inside the transaction and skips already-existing indexes atomically.
+
+## Username pattern
+
+`supervisor{i}.<orgsuffix>@example.com`
+
+- `i` is 1..N (max 5 for supervisors)
+- `orgsuffix` is deterministic — the last 8 chars of `Organization.Id`, lowercased
+- `@example.com` is a reserved TLD, safe to use per RFC 2606
+
+Deterministic pattern ⇒ any operator, any subsequent run, any skill can query for existing supervisors without shared state.
+
+## Alias construction
+
+Salesforce Alias field: **max 8 chars, alphanumeric**.
+
+Format: `omsu{i}{last-3-of-suffix}`
+
+- `omsu` prefix identifies these as Omni Supervisor agent users
+- `i` is 1 char (1..9 max — 5 supervisors max ensures we never hit 10+)
+- 3 trailing suffix chars give per-org uniqueness
+- Total: 8 chars exactly
+
+## Password pattern
+
+`SuprV1<10-char-random-hex>` — 16 chars total.
+
+Guaranteed to satisfy Salesforce's default password policy:
+- ≥1 uppercase letter (`S`, `V`)
+- ≥1 lowercase letter (from random)
+- ≥1 digit (`1`)
+- ≥1 special char (none required by default)
+- ≥8 chars total (16)
+
+Random source: `Crypto.generateAesKey(128)` → hex encode → first 10 chars.
+
+## Standard User profile
+
+**Why Standard User instead of a Supervisor-specific profile?**
+
+1. **All standard editions ship it.** Custom profiles differ per org edition.
+2. **Supervisor perms live in a PermissionSet** (`Omni_Supervisor`, assigned by `service-omni-supervisor-permset-assign`), not in the profile.
+3. **Consistent with agent skill.** Same profile, different permset. Simpler mental model for reviewers.
+
+## Debug log parsing
+
+Each successful user creation emits exactly one line to the Apex debug log:
+
+```text
+SUPERVISOR_CREATED|<userId>|<username>|<password>|<email>
+```
+
+`run-create.sh` greps this pattern with a strict regex anchored on the User Id shape (`005` + 15 alphanumerics = 18 chars) to filter out source-code echoes and comment lines that might appear in the log.
+
+## Failure modes surfaced to the skill-report
+
+| Symptom | Cause | User-friendly translation |
+|---------|-------|--------------------------|
+| `LICENSE_LIMIT_EXCEEDED` | Org is out of user license slots | "Org has reached its user license limit. Free up a license slot or request a larger CDO." |
+| `DUPLICATE_USERNAME` | Global collision (rare — deterministic suffix should prevent) | "Retry the skill; if it persists, escalate." |
+| `INVALID_EMAIL_ADDRESS` | Should never happen with @example.com | "Bug in the skill template — escalate." |
+| `INSUFFICIENT_ACCESS` | SF CLI user is not admin | "Ensure the authenticated user is System Administrator." |
+| `INVALID_SESSION_ID` | Session expired | "Re-authenticate: sf org login web -a <alias>" |

package/skills/service-omni-supervisor-users-create/references/apex-template-notes.md

@@ -0,0 +1,41 @@
+# `create-supervisors.apex.template` notes
+
+Anonymous Apex template for creating supervisor demo users. `run-create.sh` resolves the
+tokens before execution and submits the rendered Apex.
+
+## Tokens
+
+| token | meaning |
+| --- | --- |
+| `__COUNT__` | integer 1..5 — number of supervisor slots |
+| `__PROFILE_ID__` | 18-char Profile Id (typically Standard User) |
+| `__SUFFIX__` | 8-char lowercase hex string derived from `Organization.Id` |
+
+## Idempotency
+
+The block re-queries existing users inside the transaction and inserts only the truly
+missing indexes. Two concurrent runs can both pass the pre-query before either commits;
+Salesforce's `DUPLICATE_USERNAME` constraint is the authoritative deduplicator, and
+`run-create.sh` treats `DUPLICATE_USERNAME` as "another agent won the race" and retries a
+re-detect.
+
+## Security note (password / TraceFlag)
+
+This block only creates the `User` rows and never emits a password via `System.debug`. The
+caller (`run-create.sh`) sets each password with a SEPARATE Anonymous Apex
+`System.setPassword(id, pw)` submission per newly-created user. That plaintext lives in the
+submitted Apex source, which appears in the inline `executeAnonymous` debug log and — ONLY
+when a debug-log TraceFlag is active for the running user — in a queryable `ApexLog` row.
+`run-create.sh` fails closed BEFORE the first `System.setPassword`: if it cannot prove no
+active TraceFlag exists, it sets no password (the user is left `reset_required`) rather than
+risk a queryable password log.
+
+## Output contract
+
+For every user created this run, `System.debug` emits one line:
+
+```text
+SUPERVISOR_CREATED|<userId>|<username>|<email>
+```
+
+which `run-create.sh` greps from the log to build the skill's JSON return value.

package/skills/service-omni-supervisor-users-create/scripts/detect-and-create.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# detect-and-create.sh - canonical entry point: chains detect-existing.sh → run-create.sh (plan|run), idempotent, production-guarded. Args, JSON status contract, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo '{"status":"blocked","blocking_issue":"Missing required args","usage":"bash detect-and-create.sh <plan|run> <org-alias> [count=3] [profile-name=\"Standard User\"]"}' >&2
+  exit 1
+fi
+
+MODE="$1"
+ORG="$2"
+COUNT="${3:-3}"
+PROFILE_NAME="${4:-Standard User}"
+
+case "$MODE" in
+  plan|run) ;;
+  *)
+    echo "{\"status\":\"blocked\",\"blocking_issue\":\"Invalid mode '$MODE'. Expected 'plan' or 'run'.\"}" >&2
+    exit 1
+    ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DETECT_SCRIPT="$SCRIPT_DIR/detect-existing.sh"
+CREATE_SCRIPT="$SCRIPT_DIR/run-create.sh"
+
+if [ ! -f "$DETECT_SCRIPT" ]; then
+  echo "{\"status\":\"blocked\",\"blocking_issue\":\"Sibling script not found: $DETECT_SCRIPT\"}" >&2
+  exit 1
+fi
+if [ "$MODE" = "run" ] && [ ! -f "$CREATE_SCRIPT" ]; then
+  echo "{\"status\":\"blocked\",\"blocking_issue\":\"Sibling script not found: $CREATE_SCRIPT\"}" >&2
+  exit 1
+fi
+
+# Step 1: detect
+DETECT_EXIT=0
+DETECT_JSON=$(bash "$DETECT_SCRIPT" "$ORG" "$COUNT" "$PROFILE_NAME" 2>&1) || DETECT_EXIT=$?
+
+if [ "$DETECT_EXIT" -ne 0 ]; then
+  jq -n --arg raw "$DETECT_JSON" --argjson exit "$DETECT_EXIT" \
+    '{status:"blocked",blocking_issue:("detect-existing.sh exited " + ($exit|tostring)),detect_raw:$raw,create:null}'
+  exit 1
+fi
+
+if ! echo "$DETECT_JSON" | jq -e . >/dev/null 2>&1; then
+  jq -n --arg raw "$DETECT_JSON" \
+    '{status:"blocked",blocking_issue:"detect-existing.sh produced non-JSON output",detect_raw:$raw,create:null}'
+  exit 1
+fi
+
+MISSING_COUNT=$(echo "$DETECT_JSON" | jq -r '.missing_count // 0')
+SAFE_TO_WRITE=$(echo "$DETECT_JSON" | jq -r '.safe_to_write // false')
+PROFILE_ID=$(echo "$DETECT_JSON" | jq -r '.profile_id // ""')
+ORG_SUFFIX=$(echo "$DETECT_JSON" | jq -r '.org_suffix // ""')
+EXISTING_COUNT=$(echo "$DETECT_JSON" | jq -r '.existing_users | length')
+# A deactivated user in a slot is neither reusable nor recreatable (globally-unique username);
+# surface it as a manual action so a dead slot never passes as clean.
+INACTIVE_COUNT=$(echo "$DETECT_JSON" | jq -r '.inactive_count // 0')
+INACTIVE_ACTION=""
+if [ "$INACTIVE_COUNT" -gt 0 ]; then
+  INACTIVE_ACTION="$INACTIVE_COUNT supervisor slot(s) are occupied by DEACTIVATED users (see inactive_users). Their usernames are globally unique so they cannot be recreated - reactivate them in Setup → Users, or free the usernames, before those slots can be used."
+fi
+
+# Step 2: early returns. Nothing missing => "reused" (or action_needed if a dead slot is present).
+if [ "$MISSING_COUNT" = "0" ]; then
+  if [ "$INACTIVE_COUNT" -gt 0 ]; then
+    jq -n \
+      --argjson detect "$DETECT_JSON" \
+      --argjson reused_count "$EXISTING_COUNT" \
+      --arg action "$INACTIVE_ACTION" \
+      '{
+        status: "action_needed",
+        action_required: $action,
+        detect: $detect,
+        create: null,
+        created_count: 0,
+        reused_count: $reused_count,
+        total_present_after: $reused_count,
+        safe_to_write: $detect.safe_to_write
+      }'
+    exit 0
+  fi
+  jq -n \
+    --argjson detect "$DETECT_JSON" \
+    --argjson reused_count "$EXISTING_COUNT" \
+    '{
+      status: "reused",
+      detect: $detect,
+      create: null,
+      created_count: 0,
+      reused_count: $reused_count,
+      total_present_after: $reused_count,
+      safe_to_write: $detect.safe_to_write
+    }'
+  exit 0
+fi
+
+# --plan mode: never create. Report action_needed with the missing indexes (and any dead slots).
+if [ "$MODE" = "plan" ]; then
+  jq -n \
+    --argjson detect "$DETECT_JSON" \
+    --argjson reused_count "$EXISTING_COUNT" \
+    --argjson missing_count "$MISSING_COUNT" \
+    --arg inactive_action "$INACTIVE_ACTION" \
+    '{
+      status: "action_needed",
+      action_required: (
+        "Missing " + ($missing_count|tostring) + " user(s) at indexes " + ($detect.missing_indexes | map(tostring) | join(",")) + ". Re-run in --run mode to create."
+        + (if $inactive_action == "" then "" else " ALSO: " + $inactive_action end)
+      ),
+      detect: $detect,
+      create: null,
+      created_count: 0,
+      reused_count: $reused_count,
+      total_present_after: $reused_count,
+      safe_to_write: $detect.safe_to_write
+    }'
+  exit 0
+fi
+
+# Step 3: --run mode with missing users - safe_to_write guard, then create.
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  jq -n --argjson detect "$DETECT_JSON" \
+    '{status:"blocked",blocking_issue:"safe_to_write=false - refusing to create users on a production customer org.",detect:$detect,create:null,created_count:0,reused_count:0,total_present_after:0,safe_to_write:false}'
+  exit 1
+fi
+
+if [ -z "$PROFILE_ID" ] || [ -z "$ORG_SUFFIX" ]; then
+  jq -n --argjson detect "$DETECT_JSON" \
+    '{status:"blocked",blocking_issue:"detect-existing.sh did not resolve profile_id or org_suffix - cannot invoke create.",detect:$detect,create:null,created_count:0,reused_count:0,total_present_after:0,safe_to_write:$detect.safe_to_write}'
+  exit 1
+fi
+
+CREATE_EXIT=0
+CREATE_JSON=$(bash "$CREATE_SCRIPT" "$ORG" "$COUNT" "$PROFILE_ID" "$ORG_SUFFIX" 2>&1) || CREATE_EXIT=$?
+
+if [ "$CREATE_EXIT" -ne 0 ]; then
+  jq -n --argjson detect "$DETECT_JSON" --arg raw "$CREATE_JSON" --argjson exit "$CREATE_EXIT" \
+    '{status:"blocked",blocking_issue:("run-create.sh exited " + ($exit|tostring)),detect:$detect,create:null,create_raw:$raw,created_count:0,reused_count:0,total_present_after:0,safe_to_write:$detect.safe_to_write}'
+  exit 1
+fi
+
+if ! echo "$CREATE_JSON" | jq -e . >/dev/null 2>&1; then
+  jq -n --argjson detect "$DETECT_JSON" --arg raw "$CREATE_JSON" \
+    '{status:"blocked",blocking_issue:"run-create.sh produced non-JSON output",detect:$detect,create:null,create_raw:$raw,created_count:0,reused_count:0,total_present_after:0,safe_to_write:$detect.safe_to_write}'
+  exit 1
+fi
+
+CREATED_COUNT=$(echo "$CREATE_JSON" | jq -r '.created_count // 0')
+ROLLED_BACK_COUNT=$(echo "$CREATE_JSON" | jq -r '.rolled_back_users | length')
+# A created user without a working password (setPassword failed, non-destructive: stays active +
+# reset_required) is not login-ready; any pending reset forces "partial" with a manual action.
+PW_RESET_COUNT=$(echo "$CREATE_JSON" | jq -r '(.users_needing_password_reset // []) | length')
+
+# Classify: created (all landed with a password) / partial (some landed, rollbacks, or pending
+# password resets) / blocked (nothing landed).
+if [ "$CREATED_COUNT" = "0" ]; then
+  STATUS="blocked"
+elif [ "$ROLLED_BACK_COUNT" -gt 0 ] || [ "$CREATED_COUNT" -lt "$MISSING_COUNT" ] || [ "$PW_RESET_COUNT" -gt 0 ] || [ "$INACTIVE_COUNT" -gt 0 ]; then
+  STATUS="partial"
+else
+  STATUS="created"
+fi
+
+jq -n \
+  --argjson detect "$DETECT_JSON" \
+  --argjson create "$CREATE_JSON" \
+  --argjson created_count "$CREATED_COUNT" \
+  --argjson reused_count "$EXISTING_COUNT" \
+  --argjson pw_reset_count "$PW_RESET_COUNT" \
+  --arg inactive_action "$INACTIVE_ACTION" \
+  --arg status "$STATUS" \
+  '{
+    status: $status,
+    detect: $detect,
+    create: $create,
+    created_count: $created_count,
+    reused_count: $reused_count,
+    total_present_after: ($created_count + $reused_count),
+    users_needing_password_reset: ($create.users_needing_password_reset // []),
+    action_required: (
+      [
+        (if $pw_reset_count > 0 then
+          ($pw_reset_count | tostring) + " supervisor user(s) were created but could NOT have a password set automatically and cannot log in yet. Manually reset their passwords (Setup → Users → Reset Password, or `sf org open` → user record) before use. See users_needing_password_reset and CREDENTIALS.json."
+        else empty end),
+        (if $inactive_action == "" then empty else $inactive_action end)
+      ] | if length == 0 then null else join(" ") end
+    ),
+    safe_to_write: $detect.safe_to_write
+  }'
+
+case "$STATUS" in
+  created|partial) exit 0 ;;
+  blocked) exit 1 ;;
+esac

package/skills/service-omni-supervisor-users-create/scripts/detect-existing.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# detect-existing.sh - read-only probe for existing supervisor users (org/profile/existing/missing indexes); deterministic, no side effects. Args + JSON output: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Missing required argument: org-alias","usage":"bash detect-existing.sh <org-alias> [count=1] [profile-name=\"Standard User\"]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+COUNT="${2:-1}"
+PROFILE_NAME="${3:-Standard User}"
+
+if ! [[ "$COUNT" =~ ^[1-5]$ ]]; then
+  echo "{\"error\":\"Count must be an integer in range 1..5, got: $COUNT\"}" >&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
+
+ORG_JSON=$(sf data query --target-org "$ORG" --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" --json 2>/dev/null || true)
+ORG_ID=$(echo "$ORG_JSON" | jq -r '.result.records[0].Id // empty')
+IS_SANDBOX=$(echo "$ORG_JSON" | jq -r '.result.records[0].IsSandbox // false')
+TRIAL_EXP=$(echo "$ORG_JSON" | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON" | jq -r '.result.records[0].OrganizationType // "Unknown"')
+
+if [ -z "$ORG_ID" ]; then
+  echo '{"error":"Failed to query Organization.Id - check org auth and API permissions."}' >&2
+  exit 1
+fi
+
+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
+
+SUFFIX=$(echo -n "${ORG_ID:10:8}" | tr '[:upper:]' '[:lower:]')
+
+# Profile.Name is a display name; escape ' for the SOQL literal (apostrophe safety + no injection).
+PROFILE_NAME_SOQL=${PROFILE_NAME//\'/\\\'}
+PROFILE_JSON=$(sf data query --target-org "$ORG" --query "SELECT Id, Name FROM Profile WHERE Name = '$PROFILE_NAME_SOQL' LIMIT 1" --json 2>/dev/null || true)
+PROFILE_ID=$(echo "$PROFILE_JSON" | jq -r '.result.records[0].Id // empty')
+
+if [ -z "$PROFILE_ID" ]; then
+  echo "{\"error\":\"Profile '$PROFILE_NAME' not found on org '$ORG'. Check spelling - profile names are case-sensitive on some orgs and may be localized.\"}" >&2
+  exit 1
+fi
+
+USER_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, Username, IsActive FROM User WHERE Username LIKE 'supervisor%.${SUFFIX}@example.com'" \
+  --json 2>/dev/null || true)
+
+EXPECTED_USERNAMES=$(seq 1 "$COUNT" | awk -v s="$SUFFIX" '{ printf "\"supervisor%s.%s@example.com\"\n", $1, s }' | jq -s '.')
+
+FULL_JSON=$(jq -n \
+  --arg org_id "$ORG_ID" \
+  --arg org_suffix "$SUFFIX" \
+  --argjson is_sandbox "$IS_SANDBOX" \
+  --arg trial_expiration_date "$TRIAL_EXP" \
+  --arg organization_type "$ORG_TYPE" \
+  --argjson safe_to_write "$SAFE_TO_WRITE" \
+  --arg profile_id "$PROFILE_ID" \
+  --arg profile_name "$PROFILE_NAME" \
+  --argjson count "$COUNT" \
+  --argjson expected "$EXPECTED_USERNAMES" \
+  --argjson user_records "$(echo "$USER_JSON" | jq '.result.records // []')" \
+  '
+  ($user_records | map({ (.Username | ascii_downcase): {id: .Id, is_active: .IsActive} }) | add // {}) as $by_uname
+  |
+  [range(1; $count + 1) as $i
+   | ($expected[$i - 1] | ascii_downcase) as $uname
+   | if $by_uname[$uname] then
+       {index: $i, id: $by_uname[$uname].id, username: $uname, is_active: $by_uname[$uname].is_active}
+     else
+       null
+     end
+  ] as $slots
+  |
+  # occupied slots (any user present, active or not)
+  ($slots | map(select(. != null))) as $occupied
+  |
+  # existing_users: only active occupants are reusable; inactive users are surfaced separately
+  # (globally-unique username, not recreatable).
+  ($occupied | map(select(.is_active == true))) as $existing
+  |
+  ($occupied | map(select(.is_active != true))) as $inactive
+  |
+  ([range(1; $count + 1) as $i | if $slots[$i - 1] == null then $i else null end] | map(select(. != null))) as $missing
+  |
+  {
+    org_id: $org_id,
+    org_suffix: $org_suffix,
+    is_sandbox: $is_sandbox,
+    trial_expiration_date: (if $trial_expiration_date == "null" then null else $trial_expiration_date end),
+    organization_type: $organization_type,
+    safe_to_write: $safe_to_write,
+    profile_id: $profile_id,
+    profile_name: $profile_name,
+    requested_count: $count,
+    existing_users: $existing,
+    inactive_users: $inactive,
+    inactive_count: ($inactive | length),
+    missing_indexes: $missing,
+    missing_count: ($missing | length)
+  }
+  ')
+
+echo "$FULL_JSON"