@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/field-service-data-capture-migrate/scripts/json_to_flow_xml.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Convert Tooling API Flow Metadata JSON to Flow XML.
+
+Following the mechanical JSON ↔ XML mapping rule from project-codey PR #975:
+- JSON key → XML element
+- JSON array → repeated XML elements
+- Typed value wrappers preserved: {"stringValue": "X"} → <stringValue>X</stringValue>
+
+Usage:
+    json_to_flow_xml.py <input.json> <output.flow-meta.xml>
+    cat metadata.json | json_to_flow_xml.py - <output.flow-meta.xml>
+"""
+
+import json
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+
+def json_value_to_xml(parent: ET.Element, key: str, value: Any) -> None:
+    """
+    Convert a JSON value to XML element(s) under parent.
+
+    Mapping rule from PR #975:
+    - Scalar → text content
+    - Object → nested elements
+    - Array → repeated elements with same tag name
+    """
+    if value is None:
+        # Omit null values (not represented in Flow XML)
+        return
+
+    if isinstance(value, bool):
+        # Boolean → lowercase string
+        elem = ET.SubElement(parent, key)
+        elem.text = str(value).lower()
+
+    elif isinstance(value, (int, float)):
+        # Number → string
+        elem = ET.SubElement(parent, key)
+        elem.text = str(value)
+
+    elif isinstance(value, str):
+        # String → text content
+        elem = ET.SubElement(parent, key)
+        elem.text = value
+
+    elif isinstance(value, list):
+        # Array → repeated elements
+        for item in value:
+            json_value_to_xml(parent, key, item)
+
+    elif isinstance(value, dict):
+        # Object → nested element with children
+        elem = ET.SubElement(parent, key)
+        for child_key, child_value in value.items():
+            json_value_to_xml(elem, child_key, child_value)
+
+    else:
+        raise ValueError(f"Unsupported value type: {type(value)} for key '{key}'")
+
+
+def json_to_flow_xml(metadata_json: Dict[str, Any]) -> str:
+    """
+    Convert Tooling API Flow Metadata JSON to Flow XML string.
+
+    Args:
+        metadata_json: The "Metadata" object from Tooling API Flow sObject
+
+    Returns:
+        XML string with <?xml?> declaration and <Flow> root
+    """
+    # Create root <Flow> element
+    root = ET.Element("Flow")
+
+    # Convert all top-level keys to XML elements
+    for key, value in metadata_json.items():
+        json_value_to_xml(root, key, value)
+
+    # Pretty-print with indentation
+    indent_tree(root)
+
+    # Generate XML string WITHOUT namespace (simpler for testing)
+    # Salesforce accepts Flow XML without explicit xmlns on root
+    xml_str = ET.tostring(root, encoding='unicode', method='xml')
+
+    # Add XML declaration
+    return f'<?xml version="1.0" encoding="UTF-8"?>\n{xml_str}'
+
+
+def indent_tree(elem: ET.Element, level: int = 0) -> None:
+    """Add pretty-print indentation to XML tree (4 spaces per level)."""
+    indent = "    "
+    i = "\n" + level * indent
+
+    if len(elem):
+        if not elem.text or not elem.text.strip():
+            elem.text = i + indent
+        if not elem.tail or not elem.tail.strip():
+            elem.tail = i
+        for child in elem:
+            indent_tree(child, level + 1)
+        if not child.tail or not child.tail.strip():
+            child.tail = i
+    else:
+        if level and (not elem.tail or not elem.tail.strip()):
+            elem.tail = i
+
+
+def main() -> int:
+    """CLI entry point."""
+    if len(sys.argv) != 3:
+        print("Usage: json_to_flow_xml.py <input.json> <output.flow-meta.xml>", file=sys.stderr)
+        print("       cat metadata.json | json_to_flow_xml.py - <output.flow-meta.xml>", file=sys.stderr)
+        return 2
+
+    input_path = sys.argv[1]
+    output_path = sys.argv[2]
+
+    # Read input JSON
+    if input_path == "-":
+        metadata_json = json.load(sys.stdin)
+    else:
+        with open(input_path, 'r') as f:
+            metadata_json = json.load(f)
+
+    # Convert to XML
+    try:
+        xml_str = json_to_flow_xml(metadata_json)
+    except Exception as e:
+        print(f"ERROR: Failed to convert JSON to XML: {e}", file=sys.stderr)
+        return 1
+
+    # Write output
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, 'w') as f:
+        f.write(xml_str)
+
+    print(f"Converted JSON to Flow XML: {output_path}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/field-service-data-capture-migrate/scripts/manual_review_flags.py

@@ -0,0 +1,42 @@
+"""
+Manual review flag detection for field-service-data-capture-migrate.
+
+STUB: This module is not yet implemented. It returns an empty list.
+See docs/superpowers/specs/2026-08-02-manual-review-flags-design.md for the design.
+"""
+
+import xml.etree.ElementTree as ET
+from typing import List, Dict, Any
+
+
+def detect_manual_review_flags(root: ET.Element) -> List[Dict[str, Any]]:
+    """Detect patterns that require manual review in Flow Builder before activation.
+
+    Returns a list of Flag dicts, each with:
+      - code: str         # e.g. "SCREEN_IN_LOOP"
+      - element: str      # element name or screen field name
+      - what: str         # one-line "what was found"
+      - why: str          # why it needs manual review
+      - recommendation: str  # how to fix it in Flow Builder
+
+    STUB: Not yet implemented. Returns empty list.
+    """
+    return []
+
+
+def build_excision_flag(element_name: str, code: str, why: str) -> Dict[str, Any]:
+    """Build a Flag dict for a node excised at transform-time (not scan-time).
+
+    Reuses the existing Flag contract: {code, element, what, why, recommendation}.
+    Called by transform_flow.py's excise_and_placeholder — one call per excised node.
+    """
+    return {
+        "code": code,
+        "element": element_name,
+        "what": f"{element_name} was dropped — not compliant with data capture",
+        "why": why,
+        "recommendation": (
+            "Review the placeholder screen inserted at this point in the flow "
+            "and redesign in Flow Builder if the dropped logic is needed."
+        ),
+    }

package/skills/field-service-data-capture-migrate/scripts/retrieve_flow_rest.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# REST API version of retrieve_flow.sh - no SF CLI execution dependencies
+#
+# Retrieve a Flow from a Salesforce org via Tooling API using the 2-step pattern
+# from project-codey PR #975:
+#   1. GET /tooling/query to resolve Flow version ID from API name
+#   2. GET /tooling/sobjects/Flow/{id} to read Metadata JSON
+#   3. Convert JSON → XML via json_to_flow_xml.py
+#
+# Usage: retrieve_flow_rest.sh <FlowApiName> <org-alias> [output-dir]
+#   output-dir defaults to /tmp
+
+set -euo pipefail
+
+FLOW_NAME="${1:-}"
+ALIAS="${2:-}"
+OUT_DIR="${3:-/tmp}"
+
+if [[ -z "$FLOW_NAME" || -z "$ALIAS" ]]; then
+  echo "Usage: retrieve_flow_rest.sh <FlowApiName> <org-alias> [output-dir]" >&2
+  exit 2
+fi
+
+# Validate Flow API name (alphanumeric + underscore, starting with letter)
+if ! [[ "$FLOW_NAME" =~ ^[A-Za-z][A-Za-z0-9_]*$ ]]; then
+  echo "ERROR: Invalid Flow API name: '$FLOW_NAME'" >&2
+  echo "Must be alphanumeric + underscore, starting with a letter." >&2
+  exit 2
+fi
+
+mkdir -p "$OUT_DIR"
+
+echo "Retrieving Flow '$FLOW_NAME' from org '$ALIAS' via Tooling API..." >&2
+
+# Get access token and instance URL
+AUTH_JSON=$(sf org display --target-org "$ALIAS" --json 2>&1)
+if [[ $? -ne 0 ]]; then
+  echo "ERROR: Failed to authenticate to org '$ALIAS'" >&2
+  echo "$AUTH_JSON" >&2
+  exit 1
+fi
+
+ACCESS_TOKEN=$(echo "$AUTH_JSON" | jq -r '.result.accessToken // empty')
+INSTANCE_URL=$(echo "$AUTH_JSON" | jq -r '.result.instanceUrl // empty')
+
+if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" ]]; then
+  echo "ERROR: Could not get access token for org '$ALIAS'" >&2
+  echo "Run: sf org login web --alias $ALIAS" >&2
+  exit 1
+fi
+
+if [[ -z "$INSTANCE_URL" || "$INSTANCE_URL" == "null" ]]; then
+  echo "ERROR: Could not get instance URL for org '$ALIAS'" >&2
+  exit 1
+fi
+
+# Put the auth header in a curl config file rather than -H argv: command-line
+# arguments are visible to any local user via `ps`/`/proc` and would leak the
+# access token, and argv would also show up in a `set -x` trace.
+umask 077
+TEMP_JSON=""
+CURL_CFG=$(mktemp -t flow-curl-cfg.XXXXXX)
+cleanup() { rm -f "${CURL_CFG:-}" "${TEMP_JSON:-}" 2>/dev/null || true; }
+trap cleanup EXIT
+XTRACE_WAS_ON=0
+case "$-" in *x*) XTRACE_WAS_ON=1; set +x ;; esac
+{
+  printf 'header = "Authorization: Bearer %s"\n' "$ACCESS_TOKEN"
+  echo 'header = "Content-Type: application/json"'
+} > "$CURL_CFG"
+[[ "$XTRACE_WAS_ON" -eq 1 ]] && set -x
+unset ACCESS_TOKEN
+
+# Step 1: Resolve Flow version ID from API name
+echo "  [1/3] Resolving Flow version ID..." >&2
+
+SOQL="SELECT Id, LatestVersionId, ActiveVersionId FROM FlowDefinition WHERE DeveloperName='${FLOW_NAME}'"
+ENCODED_SOQL=$(python3 -c "import urllib.parse; print(urllib.parse.quote('''${SOQL}'''))")
+
+QUERY_RESPONSE=$(curl -s -w "\n%{http_code}" -X GET \
+  "${INSTANCE_URL}/services/data/v67.0/tooling/query?q=${ENCODED_SOQL}" \
+  --config "$CURL_CFG")
+
+HTTP_CODE=$(echo "$QUERY_RESPONSE" | tail -n1)
+BODY=$(echo "$QUERY_RESPONSE" | sed '$d')
+
+if [[ "$HTTP_CODE" -ge 400 ]]; then
+  echo "ERROR: Tooling API query failed (HTTP $HTTP_CODE)" >&2
+  echo "$BODY" | jq -r '.[0].message // .message // "Unknown error"' >&2
+  exit 1
+fi
+
+RECORD_COUNT=$(echo "$BODY" | jq -r '.totalSize // 0')
+if [[ "$RECORD_COUNT" -eq 0 ]]; then
+  echo "ERROR: Flow '$FLOW_NAME' not found in org '$ALIAS'" >&2
+  echo "Check the Flow API name and ensure it exists in the org." >&2
+  exit 1
+fi
+
+VERSION_ID=$(echo "$BODY" | jq -r '.records[0].LatestVersionId // empty')
+if [[ -z "$VERSION_ID" || "$VERSION_ID" == "null" ]]; then
+  echo "ERROR: FlowDefinition found but LatestVersionId is null" >&2
+  echo "$BODY" | jq '.' >&2
+  exit 1
+fi
+
+echo "  [1/3] Resolved Flow version ID: $VERSION_ID" >&2
+
+# Step 2: Read Metadata JSON
+echo "  [2/3] Reading Flow Metadata JSON..." >&2
+
+METADATA_RESPONSE=$(curl -s -w "\n%{http_code}" -X GET \
+  "${INSTANCE_URL}/services/data/v67.0/tooling/sobjects/Flow/${VERSION_ID}" \
+  --config "$CURL_CFG")
+
+HTTP_CODE=$(echo "$METADATA_RESPONSE" | tail -n1)
+BODY=$(echo "$METADATA_RESPONSE" | sed '$d')
+
+if [[ "$HTTP_CODE" -ge 400 ]]; then
+  echo "ERROR: Failed to read Flow Metadata (HTTP $HTTP_CODE)" >&2
+  echo "$BODY" | jq -r '.[0].message // .message // "Unknown error"' >&2
+  exit 1
+fi
+
+METADATA_JSON=$(echo "$BODY" | jq '.Metadata')
+if [[ "$METADATA_JSON" == "null" || -z "$METADATA_JSON" ]]; then
+  echo "ERROR: Flow response missing 'Metadata' field" >&2
+  echo "$BODY" | jq '.' >&2
+  exit 1
+fi
+
+echo "  [2/3] Retrieved Metadata JSON ($(echo "$METADATA_JSON" | jq -r 'keys | length') top-level keys)" >&2
+
+# Step 3: Convert JSON → XML
+echo "  [3/3] Converting JSON to Flow XML..." >&2
+
+TEMP_JSON=$(mktemp -t flow-metadata.XXXXXX.json)
+
+echo "$METADATA_JSON" > "$TEMP_JSON"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_XML="${OUT_DIR}/${FLOW_NAME}.flow-meta.xml"
+
+python3 "${SCRIPT_DIR}/json_to_flow_xml.py" "$TEMP_JSON" "$OUTPUT_XML" 2>&1
+if [[ $? -ne 0 ]]; then
+  echo "ERROR: JSON to XML conversion failed" >&2
+  exit 1
+fi
+
+echo "  [3/3] Conversion complete" >&2
+echo "" >&2
+echo "[OK] Flow retrieved successfully: $OUTPUT_XML" >&2
+
+# Print output path (for script chaining)
+echo "$OUTPUT_XML"

package/skills/field-service-data-capture-migrate/scripts/subflow_names.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Single source of truth for the migrated-subflow naming rule.
+
+Both transform_flow.py (which rewrites <subflows><flowName> to the DC name) and
+discover_subflow_tree.py (which predicts that name to resolve the tree) import
+this so a caller's rewritten reference always matches the migrated leaf's
+deployed name. Standard library only; no skill dependencies (safe to import
+anywhere — no circular import).
+
+Naming note: this is the migrated *flow API name*, unrelated to the DC component
+`dcName` (the Name-input extensionName) used elsewhere in the skill.
+"""
+
+# Explicit source-name -> migrated-name overrides for known mismatches where the
+# plain suffix rule is wrong. Add an entry here rather than introducing a fuzzy
+# name normalizer.
+OVERRIDES = {
+    'SDO_FSL_Image_Capture_Flow_SDO': 'SDO_FSL_Image_Capture_DC',
+}
+
+
+def migrated_dc_flow_name(source_name: str, dc_suffix: str = '_DC') -> str:
+    """The API name a migrated subflow will deploy as.
+
+    Must match exactly what transform_flow.py rewrites <subflows><flowName> to,
+    so intra-tree references resolve in the bundled dry-run.
+    """
+    if source_name in OVERRIDES:
+        return OVERRIDES[source_name]
+    if source_name.endswith(dc_suffix):
+        return source_name
+    return source_name + dc_suffix
+
+
+if __name__ == '__main__':
+    import sys
+    if len(sys.argv) < 2 or sys.argv[1] in ('-h', '--help'):
+        print("Usage: subflow_names.py <source_name> [--dc-suffix SUFFIX]", file=sys.stderr)
+        sys.exit(2)
+
+    source_name = sys.argv[1]
+    dc_suffix = '_DC'
+
+    if '--dc-suffix' in sys.argv:
+        idx = sys.argv.index('--dc-suffix')
+        if idx + 1 < len(sys.argv):
+            dc_suffix = sys.argv[idx + 1]
+
+    print(migrated_dc_flow_name(source_name, dc_suffix))