@salesforce/afv-skills 1.55.0 → 1.56.0

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

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Discover a caller flow's transitive subflow dependency tree from local XML.
+
+Reads only the flow-meta.xml files already retrieved to disk (offline,
+deterministic — never queries the org). Builds the transitive <subflows> graph,
+topologically sorts it leaves-first, classifies each node
+migratable / blocked / missing, and reports so a caller can be migrated in
+dependency order and never deployed when a dependency can't be migrated.
+
+Usage:
+    discover_subflow_tree.py <flows_dir> (<caller.flow-meta.xml> ... | --all) [--json OUT]
+
+Exit codes:
+    0  clean tree — every node is migratable
+    1  >=1 node blocked / missing / cyclic (do NOT deploy the caller)
+    2  usage error
+"""
+
+import argparse
+import json
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+NS = {'sf': 'http://soap.sforce.com/2006/04/metadata'}
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from subflow_names import migrated_dc_flow_name  # noqa: E402
+
+
+def _findall(el, tag):
+    """Direct children with or without the metadata namespace."""
+    r = el.findall(f'sf:{tag}', namespaces=NS)
+    return r if r else el.findall(tag)
+
+
+def _findtext(el, tag):
+    r = el.findtext(f'sf:{tag}', namespaces=NS)
+    return r if r is not None else el.findtext(tag)
+
+
+def _index_flows(flows_dir):
+    """API name (filename stem) -> Path for every *.flow-meta.xml in flows_dir."""
+    index = {}
+    for p in sorted(Path(flows_dir).glob('*.flow-meta.xml')):
+        api_name = p.name[:-len('.flow-meta.xml')]
+        index[api_name] = p
+    return index
+
+
+def _parse_flow(path):
+    """Return (processType, has_screens, [referenced_subflow_api_names])."""
+    root = ET.parse(path).getroot()
+    process_type = _findtext(root, 'processType')
+    has_screens = len(_findall(root, 'screens')) > 0
+    refs = []
+    for sf_el in _findall(root, 'subflows'):
+        fn = _findtext(sf_el, 'flowName')
+        if fn:
+            refs.append(fn)
+    return process_type, has_screens, refs
+
+
+def _classify(api_name, path, process_type, has_screens):
+    """Return (status, reason) for a resolvable node."""
+    if process_type != 'FieldServiceMobile':
+        return 'blocked', (
+            f"processType is '{process_type}', not 'FieldServiceMobile' — "
+            "cannot become a DataCaptureFlow"
+        )
+    if not has_screens:
+        return 'blocked', (
+            "no <screens> element — pure automation flow, cannot become a "
+            "DataCaptureFlow"
+        )
+    return 'migratable', ''
+
+
+def build_tree(flows_dir, callers):
+    """Build the transitive dependency tree for the given caller flow paths.
+
+    Returns {"order": [...leaves first...], "blocked": [...], "hasBlockers": bool}.
+    """
+    index = _index_flows(flows_dir)
+
+    nodes = {}          # api_name -> node dict
+    callers_of = {}     # api_name -> set of api_names that reference it
+    order = []          # post-order DFS accumulation (leaves first)
+    perm = set()        # fully processed
+    stack = []          # current recursion path (for cycle detection)
+
+    def record_caller(child, parent):
+        if parent is not None:
+            callers_of.setdefault(child, set()).add(parent)
+
+    def visit(api_name, path, depth, parent):
+        record_caller(api_name, parent)
+
+        if api_name in perm:
+            # Already ordered; just note the (possibly deeper) reachability.
+            if parent is not None and api_name in nodes:
+                nodes[api_name]['callers'] = sorted(callers_of.get(api_name, set()))
+            return
+
+        if api_name in stack:
+            # Cycle: mark blocked, do not descend again.
+            node = nodes.get(api_name)
+            if node is None:
+                node = {
+                    'apiName': api_name, 'file': str(path) if path else None,
+                    'migratedDcName': migrated_dc_flow_name(api_name),
+                    'processType': None, 'status': 'blocked',
+                    'reason': 'part of a subflow cycle — cannot be topologically ordered',
+                    'depth': depth, 'callers': sorted(callers_of.get(api_name, set())),
+                }
+                nodes[api_name] = node
+            else:
+                node['status'] = 'blocked'
+                node['reason'] = 'part of a subflow cycle — cannot be topologically ordered'
+            return
+
+        stack.append(api_name)
+
+        if path is None:
+            # Referenced but no file on disk.
+            nodes[api_name] = {
+                'apiName': api_name, 'file': None,
+                'migratedDcName': migrated_dc_flow_name(api_name),
+                'processType': None, 'status': 'missing',
+                'reason': 'referenced subflow has no .flow-meta.xml on disk',
+                'depth': depth, 'callers': sorted(callers_of.get(api_name, set())),
+            }
+            stack.pop()
+            perm.add(api_name)
+            order.append(nodes[api_name])
+            return
+
+        process_type, has_screens, refs = _parse_flow(path)
+
+        # Descend into children first (post-order => leaves land earlier).
+        for ref in refs:
+            visit(ref, index.get(ref), depth + 1, api_name)
+
+        status, reason = _classify(api_name, path, process_type, has_screens)
+        node = nodes.get(api_name)
+        if node is None:
+            node = {'apiName': api_name}
+            nodes[api_name] = node
+        # Preserve a cycle mark set while descending; otherwise use classification.
+        if node.get('status') == 'blocked' and 'cycle' in node.get('reason', ''):
+            pass
+        else:
+            node['status'] = status
+            node['reason'] = reason
+        node.update({
+            'file': str(path),
+            'migratedDcName': migrated_dc_flow_name(api_name),
+            'processType': process_type,
+            'depth': depth,
+            'callers': sorted(callers_of.get(api_name, set())),
+        })
+
+        stack.pop()
+        perm.add(api_name)
+        order.append(node)
+
+    for caller in callers:
+        cpath = Path(caller)
+        api_name = cpath.name[:-len('.flow-meta.xml')]
+        visit(api_name, cpath, 0, None)
+
+    blocked = [n for n in order if n['status'] != 'migratable']
+    return {'order': order, 'blocked': blocked, 'hasBlockers': bool(blocked)}
+
+
+def _render_summary(tree):
+    lines = ['Subflow dependency tree — migrate in this order (leaves first):', '']
+    for i, n in enumerate(tree['order'], 1):
+        mark = {'migratable': 'OK', 'blocked': 'BLOCKED', 'missing': 'BLOCKED'}[n['status']]
+        lines.append(f"  {i}. [{mark}] {n['apiName']}  ->  {n['migratedDcName']}")
+        if n['status'] != 'migratable':
+            lines.append(f"        reason: {n['reason']}")
+    if tree['hasBlockers']:
+        lines.append('')
+        lines.append('BLOCKED: one or more dependencies cannot be migrated — '
+                     'do NOT deploy the caller until these are resolved:')
+        for n in tree['blocked']:
+            lines.append(f"  - {n['apiName']} ({n['status']}): {n['reason']}")
+    return '\n'.join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument('flows_dir')
+    parser.add_argument('callers', nargs='*')
+    parser.add_argument('--all', action='store_true',
+                        help='treat every FieldServiceMobile flow with screens as a root')
+    parser.add_argument('--json', dest='json_out', default=None)
+    args = parser.parse_args(argv)
+
+    if not args.all and not args.callers:
+        parser.error('provide at least one caller flow path or --all')
+
+    if args.all:
+        index = _index_flows(args.flows_dir)
+        callers = []
+        for api_name, path in index.items():
+            pt, screens, _ = _parse_flow(path)
+            if pt == 'FieldServiceMobile' and screens:
+                callers.append(str(path))
+    else:
+        callers = args.callers
+
+    tree = build_tree(args.flows_dir, callers)
+
+    print(_render_summary(tree))
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(tree, indent=2))
+
+    return 1 if tree['hasBlockers'] else 0
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main())
+    except SystemExit:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        print(f'ERROR: {exc}', file=sys.stderr)
+        sys.exit(2)

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

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Shared input ingestion and validation for the field-service-data-capture-migrate skill.
+
+Both entry points (analyze_flow.py, convert_to_dc_spec.py) call
+load_and_validate_flow() to parse and validate a Field Service Mobile Flow
+metadata file before processing it. Validation is fail-fast: the first failing
+check raises FlowValidationError with a machine-readable category. Non-fatal
+issues (e.g. a missing apiVersion) are returned as a list of FlowWarning records
+alongside the parsed root.
+
+Offline only (FR-008): operates entirely on the provided file; no org connection.
+
+Namespace helpers come from flow_xml_utils (the single shared source) and are
+re-exported here so callers/tests can reference flow_input._findtext etc.
+"""
+
+import os
+import xml.etree.ElementTree as ET
+from typing import List, Optional, Tuple
+
+from flow_xml_utils import NS, _findtext, _findall, _findall_deep  # noqa: F401
+
+# Fatal validation categories (raised via FlowValidationError).
+MISSING_ARG = 'MISSING_ARG'
+FILE_NOT_FOUND = 'FILE_NOT_FOUND'
+ENCODING = 'ENCODING'
+MALFORMED_XML = 'MALFORMED_XML'
+WRONG_TYPE = 'WRONG_TYPE'
+MISSING_START = 'MISSING_START'
+SCREENLESS = 'SCREENLESS'
+
+# Non-fatal warning categories (returned, never raised).
+MISSING_API_VERSION = 'MISSING_API_VERSION'
+
+EXPECTED_PROCESS_TYPE = 'FieldServiceMobile'
+
+
+class FlowValidationError(Exception):
+    """Fatal input-validation failure. Carries a machine-readable category."""
+
+    def __init__(self, category: str, message: str, element: Optional[str] = None):
+        self.category = category
+        self.message = message
+        self.element = element
+        super().__init__(message)
+
+
+class FlowWarning:
+    """Non-fatal input finding. Named FlowWarning to avoid shadowing builtin Warning."""
+
+    def __init__(self, category: str, message: str, element: Optional[str] = None):
+        self.category = category
+        self.message = message
+        self.element = element
+
+    def __eq__(self, other) -> bool:
+        return (isinstance(other, FlowWarning)
+                and self.category == other.category
+                and self.message == other.message
+                and self.element == other.element)
+
+    def __repr__(self) -> str:
+        return f'FlowWarning(category={self.category!r}, element={self.element!r})'
+
+
+def _read_source(path: str) -> bytes:
+    """Read the file as bytes, or raise FILE_NOT_FOUND."""
+    if not os.path.isfile(path):
+        raise FlowValidationError(
+            FILE_NOT_FOUND,
+            f"[ERROR] Input file not found: '{path}'. Check the path and re-run.",
+            element=path,
+        )
+    try:
+        with open(path, 'rb') as f:
+            return f.read()
+    except OSError as e:
+        raise FlowValidationError(
+            FILE_NOT_FOUND,
+            f"[ERROR] Could not read '{path}': {e}. Check the path and permissions.",
+            element=path,
+        )
+
+
+def _decode(raw: bytes, path: str) -> str:
+    """Decode bytes as UTF-8, transparently stripping a BOM. Raise ENCODING."""
+    try:
+        return raw.decode('utf-8-sig')
+    except UnicodeDecodeError as e:
+        raise FlowValidationError(
+            ENCODING,
+            f"[ERROR] Could not decode '{path}' as UTF-8: {e}. "
+            f"Re-export the flow as UTF-8.",
+            element=path,
+        )
+
+
+def _parse(text: str, path: str) -> ET.Element:
+    """Parse decoded XML text into a root element, or raise MALFORMED_XML.
+
+    Parse from re-encoded bytes: this avoids ElementTree's refusal to accept a
+    str that still carries an <?xml ... encoding=?> declaration, and the BOM is
+    already gone (stripped in _decode).
+    """
+    try:
+        return ET.fromstring(text.encode('utf-8'))
+    except ET.ParseError as e:
+        position = getattr(e, 'position', None)
+        line = position[0] if position else '?'
+        raise FlowValidationError(
+            MALFORMED_XML,
+            f"[ERROR] Malformed XML in '{path}' at line {line}: {e}. "
+            f"Re-export the flow from Setup.",
+            element=str(line),
+        )
+
+
+def _check_process_type(root: ET.Element) -> None:
+    """Raise WRONG_TYPE unless processType is FieldServiceMobile."""
+    found = _findtext(root, 'processType')
+    if found != EXPECTED_PROCESS_TYPE:
+        shown = found if found else '(none)'
+        raise FlowValidationError(
+            WRONG_TYPE,
+            f"[ERROR] processType is '{shown}', expected "
+            f"'{EXPECTED_PROCESS_TYPE}'. Export a Field Service Mobile Flow.",
+            element=shown,
+        )
+
+
+def _check_start(root: ET.Element) -> None:
+    """Raise MISSING_START if no <start> element is present."""
+    if not _findall(root, 'start'):
+        raise FlowValidationError(
+            MISSING_START,
+            "[ERROR] No <start> element found. "
+            "File may be truncated; re-export the flow.",
+            element='start',
+        )
+
+
+def _check_screens(root: ET.Element) -> None:
+    """Raise SCREENLESS if the flow has no <screens> element."""
+    if not _findall_deep(root, 'screens'):
+        raise FlowValidationError(
+            SCREENLESS,
+            "[ERROR] Flow has no screen components; nothing to migrate. "
+            "Only screen-collecting Mobile Flows are supported.",
+            element='screens',
+        )
+
+
+def _check_api_version(root: ET.Element) -> List[FlowWarning]:
+    """Return a MISSING_API_VERSION warning when <apiVersion> is absent.
+
+    A present apiVersion never warns, at any value: there is no defined minimum
+    supported version (OQ-6 open). This discharges only the "not silent" half —
+    absence of provenance is surfaced, not guessed.
+    """
+    if _findtext(root, 'apiVersion') is None:
+        return [FlowWarning(
+            MISSING_API_VERSION,
+            "[WARNING] No <apiVersion> element found (version unspecified). "
+            "Verify the migrated flow manually.",
+            element='apiVersion',
+        )]
+    return []
+
+
+def load_and_validate_flow(path: str) -> Tuple[ET.Element, List[FlowWarning]]:
+    """Parse and validate a Field Service Mobile Flow file.
+
+    Fail-fast: the first failing check raises FlowValidationError. On success
+    returns (parsed <Flow> root, list of non-fatal warnings). Order matters —
+    each step depends on the previous succeeding, and structural checks
+    (WRONG_TYPE) precede content checks (SCREENLESS).
+    """
+    raw = _read_source(path)
+    text = _decode(raw, path)
+    root = _parse(text, path)
+    _check_process_type(root)
+    _check_start(root)
+    _check_screens(root)
+    warnings = _check_api_version(root)
+    return root, warnings

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""
+Namespace-aware ElementTree helpers for Salesforce Flow metadata XML.
+
+Flow metadata may or may not declare the Salesforce metadata namespace, so every
+lookup tries the namespaced form first and falls back to the plain tag. These
+helpers are the single shared source for flow_input.py, convert_to_dc_spec.py,
+and analyze_flow.py. This module depends on nothing else in the skill, so it is
+safe for any of them to import (no circular import).
+"""
+
+import xml.etree.ElementTree as ET
+from typing import Optional
+
+NS = {'sf': 'http://soap.sforce.com/2006/04/metadata'}
+
+
+def _findtext(el: ET.Element, tag: str) -> Optional[str]:
+    """Find direct-child text with or without namespace."""
+    result = el.findtext(f'sf:{tag}', namespaces=NS)
+    if result is None:
+        result = el.findtext(tag)
+    return result
+
+
+def _findall(el: ET.Element, tag: str) -> list:
+    """Find direct children with or without namespace."""
+    results = el.findall(f'sf:{tag}', namespaces=NS)
+    if not results:
+        results = el.findall(tag)
+    return results
+
+
+def _findall_deep(el: ET.Element, tag: str) -> list:
+    """Find all descendants with or without namespace."""
+    results = el.findall(f'.//sf:{tag}', namespaces=NS)
+    if not results:
+        results = el.findall(f'.//{tag}')
+    return results