@elastic.io/mcp 1.0.0 → 1.0.1-beta

package/dist/tools/validation.js

@@ -1,8 +1,11 @@
+import { verifyCredentials } from '../api/verification.js';
+import { credentialKey, descriptorFor, evidence, nodeCredentialArgs, nodeMetadataKey, operation } from './flow-evidence.js';
 import { logger } from '../api/logger.js';
+import { deserializeJsonApi } from '../api/jsonapi.js';
 import { resolveCredentialId } from './helpers.js';
-import { DEPRECATED_COMPONENTS, DEPRECATED_ACTIONS, BARE_FIELD_NAMES, UNSUPPORTED_ROUTER_JSONATA_FUNCTIONS, REST_API_READER_FIELDS, PLACEHOLDER_FIELD_VALUES, } from './constants.js';
-export { DEPRECATED_COMPONENTS, DEPRECATED_ACTIONS } from './constants.js';
-export function checkFlowLifecycle(flowId, discoveryState, existingFlow, operation) {
+import { DEPRECATED_COMPONENTS, getDeprecatedActionReplacement, BARE_FIELD_NAMES, UNSUPPORTED_ROUTER_JSONATA_FUNCTIONS, REST_API_READER_FIELDS, PLACEHOLDER_FIELD_VALUES, } from './constants.js';
+export { DEPRECATED_COMPONENTS, DEPRECATED_ACTIONS, DEPRECATED_COMPONENT_ACTIONS, getDeprecatedActionReplacement } from './constants.js';
+export function checkFlowLifecycle(flowId, discoveryState, existingFlow, _operation) {
     const errors = [];
     if (!discoveryState.inspectedFlows.has(flowId)) {
         errors.push(`You have not inspected flow '${flowId}' using 'get_flow' in this session. ` +
@@ -29,7 +32,7 @@ export function checkFlowBuildingGuideRead(discoveryState) {
     }
     return [];
 }
-export function stripStringLiterals(str) {
+function stripStringLiterals(str) {
     let result = '';
     let inDoubleQuote = false;
     let inSingleQuote = false;
@@ -123,6 +126,15 @@ function validateNodes(nodes, nodeMap, errors, warnings) {
             errors.push("Node definition is missing the 'id' field.");
             continue;
         }
+        const stepIdRegex = /^step_[1-9]\d*$/;
+        if (!stepIdRegex.test(node.id)) {
+            errors.push(`Node ID '${node.id}' has an invalid format. ` +
+                'Every step_id must follow the format "step_N" where N is a positive integer starting from 1 ' +
+                '(e.g., "step_1", "step_2", "step_3"). ' +
+                'Do not use formats like "step1", "Step_1", "step_0", "step_01", or custom names like "step_lk_from".');
+        }
+        if (nodeMap.has(node.id))
+            errors.push(`Duplicate node ID '${node.id}'.`);
         nodeMap.set(node.id, node);
         const command = node.command;
         if (!command) {
@@ -132,14 +144,14 @@ function validateNodes(nodes, nodeMap, errors, warnings) {
             const formatRegex = /^[^/]+\/[^:]+:[^@]+@[^@]+$/;
             if (!formatRegex.test(command)) {
                 errors.push(`Node '${node.id}' has an invalid command format: "${command}". ` +
-                    `It must be formatted as "{team_name}/{repo_name}:{action_or_trigger_id}@{latestVersionId}" ` +
-                    `(e.g., "elasticio/salesforce-v2:getUpdatedObjectsPolling@latestVersionId"). ` +
-                    `Retrieve this from the 'get_component' tool response.`);
+                    'It must be formatted as "{team_name}/{repo_name}:{action_or_trigger_id}@{latestVersionId}" ' +
+                    '(e.g., "elasticio/salesforce-v2:getUpdatedObjectsPolling@latestVersionId"). ' +
+                    'Retrieve this from the \'get_component\' tool response.');
             }
             // Check for deprecated components by command prefix
             const prefixMatch = command.match(/^([^:]+):/);
-            if (prefixMatch) {
-                const commandPrefix = prefixMatch[1];
+            const commandPrefix = prefixMatch ? prefixMatch[1] : '';
+            if (commandPrefix) {
                 const successor = DEPRECATED_COMPONENTS[commandPrefix];
                 if (successor) {
                     errors.push(`Node '${node.id}' uses deprecated component '${commandPrefix}'. ` +
@@ -147,11 +159,11 @@ function validateNodes(nodes, nodeMap, errors, warnings) {
                         `Use '${successor}' instead. Call 'list_components' to find the replacement.`);
                 }
             }
-            // Check for deprecated actions/triggers by action ID
+            // Check for deprecated actions/triggers by action ID scoped to component
             const actionMatch = command.match(/^[^:]+:([^@]+)@/);
-            if (actionMatch) {
+            if (actionMatch && commandPrefix) {
                 const actionId = actionMatch[1];
-                const replacement = DEPRECATED_ACTIONS[actionId];
+                const replacement = getDeprecatedActionReplacement(commandPrefix, actionId);
                 if (replacement) {
                     errors.push(`Node '${node.id}' uses deprecated action '${actionId}'. ` +
                         `This action is marked as deprecated in the component descriptor and shows a "Deprecated" badge in the UI. ` +
@@ -173,7 +185,7 @@ function validateNodes(nodes, nodeMap, errors, warnings) {
                             `(e.g., "$getPassthrough().step_1.${trimmedField}").`);
                     }
                     // Warn about deep $getPassthrough() paths in JSONata fields (e.g. Splitter expression).
-                    const deepPathMatch = trimmedField.match(/^\$getPassthrough\(\)\.\w+\.body\.[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)+$/);
+                    const deepPathMatch = /^\$getPassthrough\(\)\.\w+\.body\.[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)+$/.exec(trimmedField);
                     if (deepPathMatch) {
                         warnings.push(`Node '${node.id}' field '${fieldKey}' uses a deep JSONata path "${trimmedField}". ` +
                             `The UI form validator only accepts paths up to "$getPassthrough().step_X.body" — deeper paths ` +
@@ -263,25 +275,50 @@ function validateEdges(edges, nodeMap, errors, warnings) {
 function validateMapper(mapper, edgeId, errors) {
     const mapperValues = [];
     if (typeof mapper === 'string') {
-        errors.push(`Edge '${edgeId}' mapper is a string, but the UI requires an object-format mapper ` +
-            `with per-field JSONata expressions (e.g., {"fieldName": "$getPassthrough().step_1.body.value"}). ` +
-            `A string mapper breaks the UI visual mapper. Convert to object format.`);
-        mapperValues.push({ key: '_root', value: mapper });
+        const trimmed = mapper.trim();
+        // Allow root JSONata expressions: object constructors ({...}), blocks/parentheses ((...)), or array constructors ([...])
+        if (trimmed.startsWith('{') || trimmed.startsWith('(') || trimmed.startsWith('[')) {
+            mapperValues.push({ key: '_root', value: mapper });
+        }
+        else {
+            const hasOuterQuotes = (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+                (trimmed.startsWith("'") && trimmed.endsWith("'"));
+            if (!hasOuterQuotes) {
+                errors.push(`Edge '${edgeId}' mapper is a string but does not start with '{', '(', or '['. ` +
+                    `A root JSONata mapper expression must evaluate to an object or array ` +
+                    `(e.g., "{\\n  \\"fieldName\\": $getPassthrough().step_1.body.value\\n}").`);
+            }
+            mapperValues.push({ key: '_root', value: mapper });
+        }
     }
     else if (typeof mapper === 'object' && mapper !== null) {
         for (const [key, val] of Object.entries(mapper)) {
             if (Array.isArray(val)) {
-                errors.push(`Edge '${edgeId}' mapper field '${key}' is a native JSON array, but array-typed mapper fields MUST be ` +
-                    `JSONata expression strings that evaluate to an array. The UI cannot render native JSON arrays and will show empty fields. ` +
-                    `Convert it to a JSONata string, e.g.: "[{\\"role\\": \\"system\\", ...}]" instead of [{role: ...}].`);
+                for (let i = 0; i < val.length; i++) {
+                    const item = val[i];
+                    if (typeof item === 'string') {
+                        mapperValues.push({ key: `${key}[${i}]`, value: item });
+                    }
+                    else if (item && typeof item === 'object') {
+                        validateMapper(item, `${edgeId}.${key}[${i}]`, errors);
+                    }
+                    else if (typeof item === 'number' || typeof item === 'boolean') {
+                        errors.push(`Edge '${edgeId}' mapper field '${key}[${i}]' must be a JSONata expression string.`);
+                    }
+                }
             }
             else if (typeof val === 'number' || typeof val === 'boolean') {
-                mapper[key] = String(val);
-                mapperValues.push({ key, value: String(val) });
+                errors.push(`Edge '${edgeId}' mapper field '${key}' must be a JSONata expression string.`);
             }
             else if (typeof val === 'string') {
                 mapperValues.push({ key, value: val });
             }
+            else if (val && typeof val === 'object') {
+                validateMapper(val, `${edgeId}.${key}`, errors);
+            }
+            else {
+                errors.push(`Edge '${edgeId}' mapper field '${key}' must contain a JSONata expression.`);
+            }
         }
     }
     for (const { key, value } of mapperValues) {
@@ -325,6 +362,66 @@ function validateRouterCondition(condition, edgeId, errors) {
         }
     }
 }
+/** Validate graph topology: exactly one root, DAG (no cycles), all nodes reachable. */
+function validateTopology(nodes, edges, nodeMap, errors) {
+    if (nodes.length === 0)
+        return;
+    // Find root nodes (not a target of any edge)
+    const targets = new Set(edges.map(e => e.target));
+    const roots = nodes.filter(n => !targets.has(n.id));
+    if (roots.length === 0) {
+        errors.push('Flow graph has no root node (every node is a target of some edge — possible cycle).');
+        return;
+    }
+    // Exactly one node should have first:true
+    const firstNodes = nodes.filter(n => n.first);
+    if (firstNodes.length > 1) {
+        errors.push(`Multiple nodes are marked as 'first': ${firstNodes.map(n => n.id).join(', ')}. Only one trigger node should be first.`);
+    }
+    // Check for cycles using DFS
+    const adjacency = new Map();
+    for (const node of nodes)
+        adjacency.set(node.id, []);
+    for (const edge of edges)
+        adjacency.get(edge.source)?.push(edge.target);
+    const visited = new Set();
+    const inStack = new Set();
+    const hasCycle = (id) => {
+        if (inStack.has(id))
+            return true;
+        if (visited.has(id))
+            return false;
+        visited.add(id);
+        inStack.add(id);
+        for (const next of adjacency.get(id) || []) {
+            if (hasCycle(next))
+                return true;
+        }
+        inStack.delete(id);
+        return false;
+    };
+    for (const node of nodes) {
+        if (hasCycle(node.id)) {
+            errors.push('Flow graph contains a cycle, which is not allowed.');
+            return;
+        }
+    }
+    // Check all nodes are reachable from roots
+    const reachable = new Set();
+    const queue = roots.map(r => r.id);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (reachable.has(id))
+            continue;
+        reachable.add(id);
+        for (const next of adjacency.get(id) || [])
+            queue.push(next);
+    }
+    const unreachable = nodes.filter(n => !reachable.has(n.id));
+    if (unreachable.length > 0) {
+        errors.push(`Nodes not reachable from any root: ${unreachable.map(n => n.id).join(', ')}.`);
+    }
+}
 export function validateFlowGraph(body) {
     const errors = [];
     const warnings = [];
@@ -334,24 +431,26 @@ export function validateFlowGraph(body) {
     }
     const nodes = graph.nodes || [];
     const edges = graph.edges || [];
+    if (!Array.isArray(nodes) || !Array.isArray(edges))
+        return { errors: ['graph.nodes and graph.edges must be arrays.'], warnings };
     const nodeMap = new Map();
     validateNodes(nodes, nodeMap, errors, warnings);
     validateEdges(edges, nodeMap, errors, warnings);
+    validateTopology(nodes, edges, nodeMap, errors);
     return { errors, warnings };
 }
 export function checkDiscoveryState(body, discoveryState, existingFlow) {
     const errors = [];
+    const warnings = [];
     const graph = body?.data?.attributes?.graph || body?.attributes?.graph || body?.graph;
     if (!graph)
-        return errors;
+        return { errors, warnings };
     const nodes = graph.nodes || [];
-    const existingNodeIds = new Set();
     const existingComponentIds = new Set();
     const existingCredSecretIds = new Set();
     if (existingFlow) {
         const existingNodes = existingFlow?.graph?.nodes || [];
         existingNodes.forEach((n) => {
-            existingNodeIds.add(n.id);
             if (n.component_id)
                 existingComponentIds.add(n.component_id);
             const credId = resolveCredentialId(n.credentials_id);
@@ -379,7 +478,9 @@ export function checkDiscoveryState(body, discoveryState, existingFlow) {
             errors.push(`Node '${node.id}' has invalid secret_id '${rawSecId}' — must be a 24-character hex string. ` +
                 `Call 'list_secrets' to discover real secret IDs.`);
         }
-        const isExistingNode = existingNodeIds.has(node.id);
+        const oldNode = existingFlow?.graph?.nodes?.find((n) => n.id === node.id);
+        const isExistingNode = oldNode && oldNode.component_id === node.component_id && oldNode.command === node.command
+            && resolveCredentialId(oldNode.credentials_id) === rawCredId && resolveCredentialId(oldNode.secret_id) === rawSecId;
         // Discovery checks only apply to new nodes
         if (!isExistingNode) {
             if (node.component_id && !existingComponentIds.has(node.component_id) && !discoveryState.components.has(node.component_id)) {
@@ -422,92 +523,59 @@ export function checkDiscoveryState(body, discoveryState, existingFlow) {
                 `You MUST first find or create credentials/secrets using 'list_credentials'/'list_secrets' (or 'create_credentials'/'create_secret'), ` +
                 `then assign them to the node before creating or updating the flow.`);
         }
-    }
-    return errors;
-}
-/**
- * Verify a credential/secret by calling the verify-credential endpoint and polling for the result.
- * Returns { ok: true } on success or { error: string } on failure.
- */
-async function verifyCredentialForHealthCheck(client, componentId, credOrSecretId, isSecret, workspaceId) {
-    let verifyFields = {};
-    if (isSecret && workspaceId) {
-        const secretRes = await client.get(`/workspaces/${workspaceId}/secrets/${credOrSecretId}`);
-        const rawSecretSubtype = secretRes.data?.data?.attributes?.type;
-        const secretData = secretRes.data?.data?.attributes || {};
-        const existingFields = secretData.credentials || {};
-        const secretSubtype = rawSecretSubtype || secretData.type || 'noauth';
-        if (secretSubtype === 'oauth2' && existingFields.undefined_params !== undefined) {
-            const { undefined_params: existingParams = {}, ...existingOAuth } = existingFields;
-            verifyFields = { oauth: { ...existingOAuth, undefined_params: existingParams } };
-        }
-        else {
-            verifyFields = { auth: { type: secretSubtype, ...existingFields } };
+        // Warn when a Webhook step has no credentials — auth is optional but should always be proposed
+        if (node.command && typeof node.command === 'string' && /webhook.*:receive/.test(node.command)
+            && !resolveCredentialId(node.credentials_id) && !resolveCredentialId(node.secret_id)) {
+            warnings.push(`Node '${node.id}' is a Webhook trigger with no credentials attached. ` +
+                `Webhook authentication is optional but strongly recommended. Consider attaching credentials ` +
+                `to enable HMAC signature verification, API key validation, or basic auth. ` +
+                `Call 'list_credentials' for the Webhook component and ask the user which credential to attach.`);
         }
     }
-    else {
-        const credRes = await client.get(`/credentials/${credOrSecretId}`);
-        const credData = credRes.data?.data?.attributes || credRes.data?.data || {};
-        verifyFields = credData.keys || {};
-    }
-    const requestBody = {
-        data: {
-            type: 'verify-credential',
-            attributes: { fields: verifyFields },
-            relationships: {
-                workspace: { data: { id: workspaceId, type: 'workspace' } }
-            }
-        }
-    };
-    const verifyRes = await client.post(`/components/${componentId}/versions/latest/verify-credential`, requestBody);
-    const execId = verifyRes.data?.data?.id;
-    if (!execId)
-        return { ok: true }; // Can't poll, assume OK
-    // Poll for result (max 3 attempts, 3s delay)
-    const maxAttempts = 3;
-    const delayMs = 3000;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        if (attempt > 1) {
-            await new Promise(resolve => setTimeout(resolve, delayMs));
-        }
-        try {
-            const resultRes = await client.get(`/exec/result/${execId}`);
-            const resultData = resultRes.data?.data?.attributes || resultRes.data?.data || {};
-            const isPending = typeof resultData.status === 'string' && resultData.status.toLowerCase().includes('pending');
-            if (isPending)
+    return { errors, warnings };
+}
+export function checkMapperMetadataRetrieved(body, discoveryState, workspaceId = '') {
+    const graph = body?.data?.attributes?.graph || body?.attributes?.graph || body?.graph;
+    if (!graph)
+        return [];
+    const errors = [];
+    for (const edge of graph.edges || []) {
+        if (!edge.config?.mapper)
+            continue;
+        for (const id of [edge.source, edge.target]) {
+            const node = graph.nodes?.find((n) => n.id === id);
+            if (!node)
                 continue;
-            const result = resultData.result;
-            if (result?.verified === false || result?.error || result?.status === 'error') {
-                const reason = result.error || result.message || result.reason || JSON.stringify(result);
-                return { error: `Reason: ${reason}` };
+            const op = operation(node);
+            const descriptor = descriptorFor(discoveryState, node);
+            const definition = descriptor?.actions?.[op.method] || descriptor?.triggers?.[op.method];
+            if (!definition)
+                errors.push(`Call get_component for ${op.componentId} at version ${op.version} before mapping step ${id}.`);
+            else if (definition.dynamicMetadata && evidence(discoveryState).metadata.get(nodeMetadataKey(workspaceId, node))?.status !== 'VERIFIED') {
+                errors.push(`Step ${id}: retrieve successful dynamic metadata for this exact version, connection and fields before mapping.`);
             }
-            return { ok: true };
-        }
-        catch (err) {
-            const isNotReady = err.message && (err.message.includes('409') || err.message.includes('not ready'));
-            if (isNotReady)
-                continue;
-            throw err;
         }
     }
-    // Timed out polling — don't block, just warn
-    return { ok: true };
+    return [...new Set(errors)];
 }
 /**
  * Runtime health check for a flow — validates credentials, required fields, URLs, and field values.
  * Runs after create_flow/update_flow and before start_flow to catch config issues
  * that would show as red indicators in the UI.
  */
-export async function healthCheckFlow(flow, client) {
+export async function healthCheckFlow(flow, client, discoveryState) {
     const errors = [];
     const warnings = [];
+    const stepStatuses = [];
     const nodes = flow?.graph?.nodes || [];
     if (nodes.length === 0) {
         errors.push('Flow has no steps configured');
-        return { errors, warnings };
+        return { errors, warnings, stepStatuses };
     }
     for (const node of nodes) {
         const stepLabel = `Step '${node.id}' (${node.name || 'unnamed'})`;
+        const errCountBefore = errors.length;
+        const warnCountBefore = warnings.length;
         // 1. Verify credentials exist and are accessible
         const healthCredId = resolveCredentialId(node.credentials_id);
         if (healthCredId) {
@@ -542,8 +610,11 @@ export async function healthCheckFlow(flow, client) {
             const credOrSecretId = healthCredId || healthSecId;
             if (credOrSecretId) {
                 try {
-                    const verifyResult = await verifyCredentialForHealthCheck(client, node.component_id, credOrSecretId, !!healthSecId, flow?.workspace?.id || flow?.workspace?.data?.id);
-                    if (verifyResult.error) {
+                    const args = nodeCredentialArgs(flow?.workspace?.id || flow?.workspace?.data?.id, node);
+                    const verifyResult = await verifyCredentials(client, args);
+                    if (discoveryState)
+                        evidence(discoveryState).credentials.set(credentialKey(args), verifyResult);
+                    if (!verifyResult.ok) {
                         errors.push(`${stepLabel}: credential verification FAILED for '${credOrSecretId}'. ` +
                             `${verifyResult.error} ` +
                             `The credential may be expired, revoked, or the user no longer has access. ` +
@@ -551,17 +622,31 @@ export async function healthCheckFlow(flow, client) {
                     }
                 }
                 catch (err) {
-                    logger.warn(`[healthCheck] Credential verification skipped for '${credOrSecretId}': ${err instanceof Error ? err.message : String(err)}`);
+                    errors.push(`${stepLabel}: credential verification could not complete: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
         }
         // 2. Check component and required fields
         if (node.component_id) {
             try {
-                const compRes = await client.get(`/components/${node.component_id}`);
-                const comp = compRes.data?.data?.attributes || compRes.data?.data;
-                if (comp) {
+                // Use the descriptor endpoint to get actions/triggers definitions
+                const compRes = await client.get(`/components/${operation(node).componentId}/versions/${operation(node).version}/descriptor`);
+                const comp = deserializeJsonApi(compRes.data);
+                if (comp && discoveryState)
+                    evidence(discoveryState).descriptors.set(`${operation(node).componentId}@${operation(node).version}`, comp);
+                if (!comp) {
+                    errors.push(`${stepLabel}: component '${node.component_id}' returned empty data — it may be unavailable`);
+                }
+                else {
                     const actionOrTrigger = findActionOrTrigger(comp, node.command);
+                    if (node.command && !actionOrTrigger) {
+                        const commandMatch = node.command.match(/^[^:]+:([^@]+)@/);
+                        const methodId = commandMatch ? commandMatch[1] : node.command;
+                        const availableActions = Object.keys(comp.actions || {});
+                        const availableTriggers = Object.keys(comp.triggers || {});
+                        errors.push(`${stepLabel}: action/trigger '${methodId}' not found in component '${comp.name || node.component_id}'. ` +
+                            `Available actions: [${availableActions.join(', ')}], triggers: [${availableTriggers.join(', ')}]`);
+                    }
                     if (actionOrTrigger?.fields) {
                         for (const [fieldId, fieldDef] of Object.entries(actionOrTrigger.fields)) {
                             // Check required fields
@@ -587,6 +672,13 @@ export async function healthCheckFlow(flow, client) {
                         warnings.push(`${stepLabel}: component '${compName || compCommandPrefix}' is DEPRECATED. ` +
                             `Use '${successor}' instead.`);
                     }
+                    if (actionOrTrigger?.deprecated) {
+                        const commandMatch = node.command?.match(/^[^:]+:([^@]+)@/);
+                        const methodId = commandMatch ? commandMatch[1] : (node.command || '');
+                        const replacement = getDeprecatedActionReplacement(compCommandPrefix || compName, methodId);
+                        const hint = replacement ? ` Use '${replacement}' instead.` : '';
+                        warnings.push(`${stepLabel}: action/trigger '${methodId}' is marked as DEPRECATED in component '${comp.name || node.component_id}'.${hint}`);
+                    }
                     // Check if component requires auth but none is set
                     const credFields = comp.credentials?.fields;
                     const hasCredFields = credFields && Object.keys(credFields).length > 0;
@@ -596,6 +688,7 @@ export async function healthCheckFlow(flow, client) {
                 }
             }
             catch (err) {
+                errors.push(`${stepLabel}: component '${node.component_id}' could not be fetched — it may have been deleted or is not accessible`);
                 logger.warn(`[healthCheck] Could not fetch component '${node.component_id}': ${err instanceof Error ? err.message : String(err)}`);
             }
         }
@@ -631,6 +724,18 @@ export async function healthCheckFlow(flow, client) {
                 }
             }
         }
+        // Collect per-step status
+        const stepErrors = errors.slice(errCountBefore);
+        const stepWarnings = warnings.slice(warnCountBefore);
+        const commandMatch = node.command?.match(/^([^:]+):([^@]+)@/);
+        const componentName = commandMatch ? commandMatch[1] : (node.component_id || 'unknown');
+        stepStatuses.push({
+            stepId: node.id,
+            name: node.name || 'unnamed',
+            component: componentName,
+            status: stepErrors.length > 0 ? 'ERROR' : stepWarnings.length > 0 ? 'WARNING' : 'OK',
+            issues: [...stepErrors, ...stepWarnings],
+        });
     }
     // 5. Check edges with missing mappers for non-first target steps.
     // Missing mappers cause empty/red fields in the UI.
@@ -646,77 +751,13 @@ export async function healthCheckFlow(flow, client) {
             }
         }
     }
-    // 6. Validate mapper fields against component input schema types.
-    // If a field is defined as type:"array" in the schema but the mapper value is a plain
-    // string passthrough (not a JSONata array expression), warn that it needs to be an array expression.
-    for (const edge of edges) {
-        const edgeId = edge.id || `${edge.source}:${edge.target}`;
-        const mapper = edge.config?.mapper;
-        if (!mapper || typeof mapper !== 'object' || Array.isArray(mapper))
-            continue;
-        const targetNode = nodes.find((n) => n.id === edge.target);
-        if (!targetNode?.component_id)
-            continue;
-        try {
-            const compRes = await client.get(`/components/${targetNode.component_id}`);
-            const comp = compRes.data?.data?.attributes || compRes.data?.data;
-            if (!comp)
-                continue;
-            const actionOrTrigger = findActionOrTrigger(comp, targetNode.command);
-            const inputSchema = actionOrTrigger?.metadata?.in?.properties;
-            // For components with dynamicMetadata and no static input schema,
-            // we can't verify field types statically. Warn if any mapper field name
-            // contains common array-indicating patterns (e.g. "urls", "items", "files", "messages")
-            // and the value is not a JSONata array expression.
-            if (!inputSchema && actionOrTrigger?.dynamicMetadata === true) {
-                const arrayFieldPatterns = /^(file_urls|urls|items|files|messages|recipients|attachments|records|entries|rows|contacts|emails)$/i;
-                for (const [fieldKey, fieldValue] of Object.entries(mapper)) {
-                    if (typeof fieldValue === 'string' && arrayFieldPatterns.test(fieldKey)) {
-                        const trimmed = fieldValue.trim();
-                        if (!trimmed.startsWith('[')) {
-                            warnings.push(`Edge '${edgeId}' mapper field '${fieldKey}' looks like an array-typed field (dynamicMetadata component) ` +
-                                `but is mapped as a plain string "${trimmed}". The UI visual mapper cannot render array fields mapped ` +
-                                `as plain passthroughs — it shows "impossible to map properties not inside the array property". ` +
-                                `Use a JSONata array expression starting with "[" to construct the array inline, e.g.: ` +
-                                `"[{\\"file_url\\": $getPassthrough().step_X.body.file_url}]". ` +
-                                `The mapping works at runtime but causes red indicators in the UI.`);
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!inputSchema)
-                continue;
-            for (const [fieldKey, fieldValue] of Object.entries(mapper)) {
-                const schemaDef = inputSchema[fieldKey];
-                // Check array-typed fields mapped as plain strings
-                if (schemaDef?.type === 'array' && typeof fieldValue === 'string') {
-                    const trimmed = fieldValue.trim();
-                    // A valid array mapper should start with "[" (JSONata array expression)
-                    if (!trimmed.startsWith('[')) {
-                        const itemProps = schemaDef.items?.properties || schemaDef.items?.type;
-                        const hint = typeof itemProps === 'object'
-                            ? `Expected format: [{"${Object.keys(itemProps)[0]}": ...}]`
-                            : `Expected a JSONata expression that evaluates to an array`;
-                        errors.push(`Edge '${edgeId}' mapper field '${fieldKey}' is mapped as a plain string, but the component schema ` +
-                            `defines it as type "array". A plain string passthrough will cause a type mismatch (red field in the UI). ` +
-                            `${hint}. Wrap the value in a JSONata array expression, e.g.: ` +
-                            `"[{\\"field\\": $getPassthrough().step_X.body.value}]".`);
-                    }
-                }
-            }
-        }
-        catch {
-            // Component fetch may have already been done above; skip on error
-        }
-    }
-    return { errors, warnings };
+    return { errors, warnings, stepStatuses };
 }
 /** Find action or trigger definition by parsing the command string */
 function findActionOrTrigger(component, command) {
     if (!command)
         return null;
-    const match = command.match(/^[^:]+:([^@]+)@/);
+    const match = /^[^:]+:([^@]+)@/.exec(command);
     if (!match)
         return null;
     const methodId = match[1];
@@ -724,10 +765,18 @@ function findActionOrTrigger(component, command) {
 }
 /** Format health check results as a readable string to append to tool response */
 export function formatHealthCheck(result) {
-    if (result.errors.length === 0 && result.warnings.length === 0) {
-        return '\n\nHealth check passed — no issues found.';
-    }
     const parts = ['\n\n--- Flow Health Check ---'];
+    // Per-step status summary
+    if (result.stepStatuses && result.stepStatuses.length > 0) {
+        parts.push('\nStep Validation:');
+        for (const step of result.stepStatuses) {
+            const icon = step.status === 'OK' ? '[OK]' : step.status === 'WARNING' ? '[WARN]' : '[FAIL]';
+            parts.push(`  ${icon} ${step.stepId} (${step.name}) — ${step.component}`);
+            for (const issue of step.issues) {
+                parts.push(`        ${issue}`);
+            }
+        }
+    }
     if (result.errors.length > 0) {
         parts.push(`\nERRORS (${result.errors.length}):`);
         for (const err of result.errors) {
@@ -740,7 +789,10 @@ export function formatHealthCheck(result) {
             parts.push(`  - ${warn}`);
         }
     }
-    if (result.errors.length > 0) {
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+        parts.push('\nAll steps validated successfully.');
+    }
+    else if (result.errors.length > 0) {
         parts.push('\nFix the errors above before starting the flow.');
     }
     return parts.join('\n');