@elastic.io/mcp 1.0.0

package/dist/tools/validation.js

@@ -0,0 +1,748 @@
+import { logger } from '../api/logger.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) {
+    const errors = [];
+    if (!discoveryState.inspectedFlows.has(flowId)) {
+        errors.push(`You have not inspected flow '${flowId}' using 'get_flow' in this session. ` +
+            `Playbook B requires you to call 'get_flow' FIRST to inspect the current graph before making modifications. ` +
+            `Call 'get_flow' with flowId '${flowId}' and review the result before retrying.`);
+    }
+    if (existingFlow) {
+        const status = existingFlow.status || existingFlow.attributes?.status;
+        if (status === 'active') {
+            errors.push(`Flow '${flowId}' is currently ACTIVE (status: "${status}"). ` +
+                `Playbook B requires you to call 'stop_flow' and wait until the flow is inactive BEFORE applying modifications. ` +
+                `Call 'stop_flow' with flowId '${flowId}', then poll 'get_flow' until the status is "inactive", then retry.`);
+        }
+    }
+    return errors;
+}
+export function checkFlowBuildingGuideRead(discoveryState) {
+    if (!discoveryState.flowBuildingGuideRead) {
+        return [
+            `You have NOT read the 'elasticio://docs/flow-building-guide' resource in this session. ` +
+                `Rule 5 requires you to read this resource BEFORE creating or updating any flow to retrieve the correct JSON payload structures, schemas, and mapping rules. ` +
+                `Read the resource 'elasticio://docs/flow-building-guide' first, then retry.`
+        ];
+    }
+    return [];
+}
+export function stripStringLiterals(str) {
+    let result = '';
+    let inDoubleQuote = false;
+    let inSingleQuote = false;
+    let escaped = false;
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+            continue;
+        }
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+            continue;
+        }
+        if (!inDoubleQuote && !inSingleQuote) {
+            result += char;
+        }
+    }
+    return result;
+}
+/**
+ * Validate REST API reader fields on a node (url quoting, headers format, body format).
+ * Shared between validateFlowGraph (pre-submit) and healthCheckFlow (post-submit).
+ */
+function validateRestApiReader(reader, stepLabel, errors, warnings) {
+    // Check for plain URLs in JSONata-mode fields
+    for (const [fieldKey, fieldValue] of Object.entries(reader)) {
+        if (typeof fieldValue === 'string') {
+            const trimmedVal = fieldValue.trim();
+            if (/^https?:\/\//i.test(trimmedVal)) {
+                errors.push(`${stepLabel} field 'reader.${fieldKey}' contains a plain URL "${trimmedVal}" which is invalid JSONata syntax ` +
+                    `(the ":" in the protocol causes a parse error). ` +
+                    `This field uses JSONata Mode — wrap the URL in escaped double quotes so it is treated as a string literal: ` +
+                    `"\\\"${trimmedVal}\\\"".`);
+            }
+        }
+    }
+    // Headers must be array of {key, value}, not a plain object
+    if (reader.headers && !Array.isArray(reader.headers)) {
+        errors.push(`${stepLabel} field 'reader.headers' is a plain object, but the REST API V2 component (RESTAPIView) ` +
+            `requires headers as an array of {key, value} pairs: [{"key": "Content-Type", "value": "\"application/json\"", "frozen": true}]. ` +
+            `Passing a plain object causes "TypeError: r.map is not a function" in the frontend.`);
+    }
+    // Body format for POST/PUT/PATCH
+    const method = reader.method;
+    if (method && ['POST', 'PUT', 'PATCH'].includes(method.toUpperCase())) {
+        const body = reader.body;
+        if (!body) {
+            errors.push(`${stepLabel} uses HTTP method '${method}' but 'reader.body' is missing. ` +
+                `For POST/PUT/PATCH requests, you MUST include a body object: ` +
+                `{"raw": "<JSONata expression or static JSON>", "formData": [], "urlencoded": [], "contentType": "application/json"}.`);
+        }
+        else if (typeof body === 'string') {
+            errors.push(`${stepLabel} field 'reader.body' is a plain string, but it MUST be an object: ` +
+                `{"raw": "${body}", "formData": [], "urlencoded": [], "contentType": "application/json"}. ` +
+                `Passing a string causes "TypeError: Cannot create property 'raw' on string" in the frontend.`);
+        }
+        else if (typeof body === 'object') {
+            if (body.raw === undefined) {
+                errors.push(`${stepLabel} field 'reader.body' is missing the 'raw' property. ` +
+                    `Body must include: {"raw": "<content>", "formData": [], "urlencoded": [], "contentType": "application/json"}.`);
+            }
+            else if (body.raw === '' || body.raw === null) {
+                warnings.push(`${stepLabel} field 'reader.body.raw' is empty — the ${method} request will send no data. ` +
+                    `Set it to a JSONata expression (e.g., "$getPassthrough().step_X.body") or a static JSON string.`);
+            }
+            if (!Array.isArray(body.formData)) {
+                errors.push(`${stepLabel} field 'reader.body.formData' must be an array (use [] if not needed).`);
+            }
+            if (!Array.isArray(body.urlencoded)) {
+                errors.push(`${stepLabel} field 'reader.body.urlencoded' must be an array (use [] if not needed).`);
+            }
+            if (!body.contentType) {
+                errors.push(`${stepLabel} field 'reader.body.contentType' is missing. Set it to the body content type (e.g., "application/json").`);
+            }
+        }
+    }
+}
+/** Validate all nodes in a flow graph: id, command format, deprecated components/actions, fields. */
+function validateNodes(nodes, nodeMap, errors, warnings) {
+    for (const node of nodes) {
+        if (!node.id) {
+            errors.push("Node definition is missing the 'id' field.");
+            continue;
+        }
+        nodeMap.set(node.id, node);
+        const command = node.command;
+        if (!command) {
+            errors.push(`Node '${node.id}' is missing the 'command' field.`);
+        }
+        else {
+            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.`);
+            }
+            // Check for deprecated components by command prefix
+            const prefixMatch = command.match(/^([^:]+):/);
+            if (prefixMatch) {
+                const commandPrefix = prefixMatch[1];
+                const successor = DEPRECATED_COMPONENTS[commandPrefix];
+                if (successor) {
+                    errors.push(`Node '${node.id}' uses deprecated component '${commandPrefix}'. ` +
+                        `This component is no longer supported and may not work correctly in the UI. ` +
+                        `Use '${successor}' instead. Call 'list_components' to find the replacement.`);
+                }
+            }
+            // Check for deprecated actions/triggers by action ID
+            const actionMatch = command.match(/^[^:]+:([^@]+)@/);
+            if (actionMatch) {
+                const actionId = actionMatch[1];
+                const replacement = DEPRECATED_ACTIONS[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. ` +
+                        `Use '${replacement}' instead. Call 'get_component' to verify available non-deprecated actions.`);
+                }
+            }
+        }
+        // Validate JSONata-mode node fields (e.g. Splitter's "expression") for bare references
+        // that should use $getPassthrough() paths
+        if (node.fields && node.component_id) {
+            for (const [fieldKey, fieldValue] of Object.entries(node.fields)) {
+                if (typeof fieldValue === 'string') {
+                    const trimmedField = fieldValue.trim();
+                    // Catch bare "body" or "body.something" that should be $getPassthrough().step_id.body
+                    if (/^body(\.[a-zA-Z_]\w*)*$/.test(trimmedField)) {
+                        errors.push(`Node '${node.id}' field '${fieldKey}' contains a bare reference "${trimmedField}" which will resolve to empty/undefined at runtime. ` +
+                            `If this is a JSONata expression field (e.g. Splitter expression), you MUST use the passthrough path format: ` +
+                            `"$getPassthrough().step_id.${trimmedField}" where step_id is the ID of the step that produces the data ` +
+                            `(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*)+$/);
+                    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 ` +
+                            `cause a red indicator and blocked Continue button in the UI, even though they work at runtime. ` +
+                            `Consider using "$getPassthrough().step_X.body" and restructuring the incoming data to send the array ` +
+                            `directly as the webhook/trigger body, or add a Code component before the Splitter to extract the nested array.`);
+                    }
+                }
+            }
+        }
+        // Validate placeholder/dummy values in fields that use dynamic select models.
+        if (node.fields) {
+            for (const [fieldKey, fieldValue] of Object.entries(node.fields)) {
+                if (typeof fieldValue === 'string' && PLACEHOLDER_FIELD_VALUES.includes(fieldValue)) {
+                    warnings.push(`Node '${node.id}' field '${fieldKey}' has a placeholder value "${fieldValue}" which likely means it was never ` +
+                        `properly configured via a dynamic select model. Call 'init_dynamic_select_model' to retrieve the valid options ` +
+                        `and select a real value.`);
+                }
+            }
+        }
+        // Validate REST API reader fields
+        if (node.fields?.reader && typeof node.fields.reader === 'object') {
+            validateRestApiReader(node.fields.reader, `Node '${node.id}'`, errors, warnings);
+        }
+    }
+}
+/** Validate all edges in a flow graph: references, mappers, router conditions. */
+function validateEdges(edges, nodeMap, errors, warnings) {
+    // Identify router nodes for condition validation
+    const routerNodeIds = new Set();
+    for (const [id, node] of nodeMap) {
+        if (node.command && /router:route/.test(node.command)) {
+            routerNodeIds.add(id);
+        }
+    }
+    for (const edge of edges) {
+        const edgeId = edge.id || `${edge.source}:${edge.target}`;
+        if (!edge.source || !edge.target) {
+            errors.push(`Edge '${edgeId}' is missing 'source' or 'target' properties.`);
+            continue;
+        }
+        if (!nodeMap.has(edge.source)) {
+            errors.push(`Edge '${edgeId}' references source step '${edge.source}' which does not exist in the graph.`);
+        }
+        if (!nodeMap.has(edge.target)) {
+            errors.push(`Edge '${edgeId}' references target step '${edge.target}' which does not exist in the graph.`);
+        }
+        // Warn when edge has no mapper config at all for a non-first target step.
+        if (!edge.config?.mapper) {
+            const targetNode = nodeMap.get(edge.target);
+            if (targetNode && !targetNode.first) {
+                warnings.push(`Edge '${edgeId}' has no mapper configuration. Target step '${edge.target}' (${targetNode.name || 'unnamed'}) ` +
+                    `will receive no mapped data from '${edge.source}', causing empty fields in the UI. ` +
+                    `Add a 'config' with 'mapper_type: "jsonata"' and a 'mapper' object that maps the target step's input fields ` +
+                    `using $getPassthrough() paths. For array-typed input fields, use JSONata array expressions starting with "[".`);
+            }
+        }
+        const mapper = edge.config?.mapper;
+        if (mapper) {
+            validateMapper(mapper, edgeId, errors);
+        }
+        // Validate router edge conditions for unsupported JSONata functions
+        if (edge.config?.condition && routerNodeIds.has(edge.source)) {
+            validateRouterCondition(edge.config.condition, edgeId, errors);
+        }
+        // Check for REST API reader fields misplaced in edge mapper.
+        if (mapper && typeof mapper === 'object' && !Array.isArray(mapper)) {
+            const targetNode = nodeMap.get(edge.target);
+            if (targetNode?.fields?.reader || targetNode?.command?.includes('rest-api-component') || targetNode?.command?.includes('REST-API')) {
+                const misplacedFields = REST_API_READER_FIELDS.filter(f => f in mapper);
+                if (misplacedFields.length > 0) {
+                    errors.push(`Edge '${edgeId}' mapper contains REST API reader fields [${misplacedFields.join(', ')}] ` +
+                        `that belong in the target node's 'fields.reader' object, NOT in the edge mapper. ` +
+                        `Move these to node '${edge.target}' fields.reader and remove them from the edge mapper. ` +
+                        `The edge mapper should only map input metadata fields.`);
+                }
+            }
+        }
+        // Check that router edges have conditions
+        if (routerNodeIds.has(edge.source) && !edge.config?.condition) {
+            errors.push(`Edge '${edgeId}' originates from router step '${edge.source}' but has no 'condition' in its config. ` +
+                `All outgoing edges from a router MUST have a 'condition' property with a JSONata boolean expression.`);
+        }
+    }
+}
+/** Validate mapper format and JSONata expressions within an edge mapper. */
+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 });
+    }
+    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: ...}].`);
+            }
+            else if (typeof val === 'number' || typeof val === 'boolean') {
+                mapper[key] = String(val);
+                mapperValues.push({ key, value: String(val) });
+            }
+            else if (typeof val === 'string') {
+                mapperValues.push({ key, value: val });
+            }
+        }
+    }
+    for (const { key, value } of mapperValues) {
+        const fieldLabel = key === '_root' ? `mapper` : `mapper field '${key}'`;
+        const trimmed = value.trim();
+        const hasOuterQuotes = (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"));
+        if (hasOuterQuotes) {
+            const inner = trimmed.substring(1, trimmed.length - 1).trim();
+            if (inner.startsWith('{') || inner.startsWith('[') || inner.startsWith('$')) {
+                errors.push(`Edge '${edgeId}' ${fieldLabel} appears to be wrapped in outer double or single quotes: \`${value}\`. ` +
+                    `This turns the JSONata expression into a static string literal, preventing variables and functions from resolving. ` +
+                    `Make sure the JSONata expression value itself starts directly with the path, function, or object definition, without outer wrapping quotes.`);
+            }
+        }
+        const strippedValue = stripStringLiterals(trimmed);
+        for (const field of BARE_FIELD_NAMES) {
+            const fieldRegex = new RegExp(`(?<![$.])\\b${field}\\b(?!\\s*:)`, 'g');
+            if (fieldRegex.test(strippedValue)) {
+                errors.push(`Edge '${edgeId}' ${fieldLabel} uses direct variable reference \`${field}\` which does not resolve. ` +
+                    `You MUST ALWAYS use the dynamic passthrough path format: \`$getPassthrough().step_id.body.${field}\`, ` +
+                    `where \`step_id\` is the ID of the step that produced the data (e.g., \`$getPassthrough().step_1.body.${field}\`).`);
+            }
+        }
+    }
+}
+/** Validate a router edge condition for unsupported JSONata functions. */
+function validateRouterCondition(condition, edgeId, errors) {
+    if (typeof condition !== 'string')
+        return;
+    const strippedCondition = stripStringLiterals(condition);
+    for (const fn of UNSUPPORTED_ROUTER_JSONATA_FUNCTIONS) {
+        // Escape the leading $ so it's matched literally, not as a regex anchor
+        const escapedFn = fn.replace(/\$/g, '\\$');
+        const fnRegex = new RegExp(`${escapedFn}\\s*\\(`, 'g');
+        if (fnRegex.test(strippedCondition)) {
+            errors.push(`Edge '${edgeId}' router condition uses '${fn}()' which is NOT available in the router condition context ` +
+                `and will cause "Attempted to invoke a non-function" error at runtime. ` +
+                `Use $substring() on date strings from passthrough data instead. ` +
+                `For example, to extract the hour from a fireTime: $substring($getPassthrough().step_1.body.fireTime, 11, 2) < "12".`);
+        }
+    }
+}
+export function validateFlowGraph(body) {
+    const errors = [];
+    const warnings = [];
+    const graph = body?.data?.attributes?.graph || body?.attributes?.graph || body?.graph;
+    if (!graph) {
+        return { errors, warnings };
+    }
+    const nodes = graph.nodes || [];
+    const edges = graph.edges || [];
+    const nodeMap = new Map();
+    validateNodes(nodes, nodeMap, errors, warnings);
+    validateEdges(edges, nodeMap, errors, warnings);
+    return { errors, warnings };
+}
+export function checkDiscoveryState(body, discoveryState, existingFlow) {
+    const errors = [];
+    const graph = body?.data?.attributes?.graph || body?.attributes?.graph || body?.graph;
+    if (!graph)
+        return errors;
+    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);
+            if (credId)
+                existingCredSecretIds.add(credId);
+            const secId = resolveCredentialId(n.secret_id);
+            if (secId)
+                existingCredSecretIds.add(secId);
+        });
+    }
+    const OBJECT_ID_RE = /^[0-9a-f]{24}$/;
+    for (const node of nodes) {
+        // Format validation: component_id, credentials_id, secret_id must be valid 24-char hex ObjectIDs
+        if (node.component_id && !OBJECT_ID_RE.test(node.component_id)) {
+            errors.push(`Node '${node.id}' has invalid component_id '${node.component_id}' — must be a 24-character hex string (MongoDB ObjectID). ` +
+                `Do NOT use placeholder IDs from documentation examples. Call 'list_components' to discover real component IDs.`);
+        }
+        const rawCredId = resolveCredentialId(node.credentials_id);
+        if (rawCredId && !OBJECT_ID_RE.test(rawCredId)) {
+            errors.push(`Node '${node.id}' has invalid credentials_id '${rawCredId}' — must be a 24-character hex string. ` +
+                `Call 'list_credentials' to discover real credential IDs.`);
+        }
+        const rawSecId = resolveCredentialId(node.secret_id);
+        if (rawSecId && !OBJECT_ID_RE.test(rawSecId)) {
+            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);
+        // Discovery checks only apply to new nodes
+        if (!isExistingNode) {
+            if (node.component_id && !existingComponentIds.has(node.component_id) && !discoveryState.components.has(node.component_id)) {
+                errors.push(`Node '${node.id}' references component ID '${node.component_id}', but you have not read its schema using 'get_component'. ` +
+                    `You MUST call 'get_component' for this component first to retrieve its official actions, triggers, and fields schema.`);
+            }
+            const nodeCredId = resolveCredentialId(node.credentials_id);
+            if (nodeCredId && !existingCredSecretIds.has(nodeCredId) && !discoveryState.credentials.has(nodeCredId)) {
+                errors.push(`Node '${node.id}' references credential ID '${nodeCredId}', but you have not listed or discovered credentials for component '${node.component_id}' in this workspace. ` +
+                    `You MUST search/list credentials via 'list_credentials' first before configuring them in the flow.`);
+            }
+            const nodeSecId = resolveCredentialId(node.secret_id);
+            if (nodeSecId && !existingCredSecretIds.has(nodeSecId) && !discoveryState.secrets.has(nodeSecId)) {
+                errors.push(`Node '${node.id}' references secret ID '${nodeSecId}', but you have not listed or discovered secrets for component '${node.component_id}' in this workspace. ` +
+                    `You MUST search/list secrets via 'list_secrets' first before configuring them in the flow.`);
+            }
+        }
+        // Check secret state for ALL nodes (existing and new)
+        const secId = resolveCredentialId(node.secret_id);
+        if (secId && discoveryState.secrets.has(secId)) {
+            const secretState = discoveryState.secrets.get(secId);
+            if (secretState && secretState !== 'ready') {
+                errors.push(`Node '${node.id}' uses secret '${secId}' which is in '${secretState}' state. ` +
+                    `Only secrets in 'ready' state can be used in flows. Please re-authenticate or choose a different secret.`);
+            }
+        }
+        // Check credential/secret verification results for ALL nodes
+        const credIdForVerify = resolveCredentialId(node.credentials_id) || resolveCredentialId(node.secret_id);
+        if (credIdForVerify && discoveryState.credentialVerifications.has(credIdForVerify)) {
+            const verification = discoveryState.credentialVerifications.get(credIdForVerify);
+            if (verification && !verification.ok) {
+                errors.push(`Node '${node.id}' uses credential/secret '${credIdForVerify}' which FAILED verification: ${verification.error}. ` +
+                    `Fix or replace this credential/secret before using it in a flow.`);
+            }
+        }
+        // Auth check applies to ALL nodes (existing and new)
+        if (node.component_id && discoveryState.componentsRequiringAuth.has(node.component_id)
+            && !resolveCredentialId(node.credentials_id) && !resolveCredentialId(node.secret_id)) {
+            errors.push(`Node '${node.id}' uses component '${node.component_id}' which requires authentication, but no credentials_id or secret_id is set. ` +
+                `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 } };
+        }
+    }
+    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)
+                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}` };
+            }
+            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 };
+}
+/**
+ * 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) {
+    const errors = [];
+    const warnings = [];
+    const nodes = flow?.graph?.nodes || [];
+    if (nodes.length === 0) {
+        errors.push('Flow has no steps configured');
+        return { errors, warnings };
+    }
+    for (const node of nodes) {
+        const stepLabel = `Step '${node.id}' (${node.name || 'unnamed'})`;
+        // 1. Verify credentials exist and are accessible
+        const healthCredId = resolveCredentialId(node.credentials_id);
+        if (healthCredId) {
+            try {
+                await client.get(`/credentials/${healthCredId}`);
+            }
+            catch {
+                errors.push(`${stepLabel}: credential '${healthCredId}' could not be fetched — it may have been deleted`);
+            }
+        }
+        const healthSecId = resolveCredentialId(node.secret_id);
+        if (healthSecId) {
+            try {
+                const workspaceId = flow?.workspace?.id || flow?.workspace?.data?.id;
+                if (workspaceId) {
+                    const secretRes = await client.get(`/workspaces/${workspaceId}/secrets/${healthSecId}`);
+                    const secret = secretRes.data?.data;
+                    const state = secret?.attributes?.state;
+                    if (state && state !== 'ready') {
+                        errors.push(`${stepLabel}: secret '${healthSecId}' is in state '${state}', expected 'ready'`);
+                    }
+                }
+            }
+            catch {
+                errors.push(`${stepLabel}: secret '${healthSecId}' could not be fetched — it may have been deleted`);
+            }
+        }
+        // 1b. Verify credentials actually work by calling verify-credential endpoint.
+        // A credential/secret can exist and be in "ready" state but still fail at runtime
+        // (e.g. OAuth token revoked, API key disabled, 403 Forbidden).
+        if (node.component_id) {
+            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) {
+                        errors.push(`${stepLabel}: credential verification FAILED for '${credOrSecretId}'. ` +
+                            `${verifyResult.error} ` +
+                            `The credential may be expired, revoked, or the user no longer has access. ` +
+                            `Re-authorize the credential in the UI or replace it with a working one.`);
+                    }
+                }
+                catch (err) {
+                    logger.warn(`[healthCheck] Credential verification skipped for '${credOrSecretId}': ${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) {
+                    const actionOrTrigger = findActionOrTrigger(comp, node.command);
+                    if (actionOrTrigger?.fields) {
+                        for (const [fieldId, fieldDef] of Object.entries(actionOrTrigger.fields)) {
+                            // Check required fields
+                            if (fieldDef.required && (!node.fields || node.fields[fieldId] === undefined || node.fields[fieldId] === '')) {
+                                errors.push(`${stepLabel}: required field '${fieldId}' (${fieldDef.label || fieldId}) is not set`);
+                            }
+                            // Check static select model values
+                            if (fieldDef.model && typeof fieldDef.model === 'object' && node.fields?.[fieldId]) {
+                                const allowedKeys = Object.keys(fieldDef.model);
+                                if (!allowedKeys.includes(node.fields[fieldId])) {
+                                    warnings.push(`${stepLabel}: field '${fieldId}' has value '${node.fields[fieldId]}' which is not in the ` +
+                                        `allowed static values: ${allowedKeys.join(', ')}. This may be valid if the field uses a dynamic model.`);
+                                }
+                            }
+                        }
+                    }
+                    // Check if component is deprecated
+                    const compName = comp.name || '';
+                    const compCommandPrefix = comp.team_name && comp.repo_name
+                        ? `${comp.team_name}/${comp.repo_name}` : '';
+                    const successor = DEPRECATED_COMPONENTS[compName] || DEPRECATED_COMPONENTS[compCommandPrefix];
+                    if (successor) {
+                        warnings.push(`${stepLabel}: component '${compName || compCommandPrefix}' is DEPRECATED. ` +
+                            `Use '${successor}' instead.`);
+                    }
+                    // Check if component requires auth but none is set
+                    const credFields = comp.credentials?.fields;
+                    const hasCredFields = credFields && Object.keys(credFields).length > 0;
+                    if (hasCredFields && !resolveCredentialId(node.credentials_id) && !resolveCredentialId(node.secret_id)) {
+                        errors.push(`${stepLabel}: component requires authentication but no credentials or secret is configured`);
+                    }
+                }
+            }
+            catch (err) {
+                logger.warn(`[healthCheck] Could not fetch component '${node.component_id}': ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // 3. Validate REST API reader format (headers, body for POST/PUT/PATCH)
+        if (node.fields?.reader && typeof node.fields.reader === 'object') {
+            validateRestApiReader(node.fields.reader, stepLabel, errors, warnings);
+        }
+        // 4. Validate URLs (REST API, webhooks)
+        if (node.fields?.reader?.url) {
+            const url = node.fields.reader.url;
+            // Check for plain URL in JSONata-mode field (reader fields use JSONata Mode)
+            if (/^https?:\/\//i.test(url.trim())) {
+                errors.push(`${stepLabel}: reader.url contains a plain URL "${url}" which is invalid JSONata syntax ` +
+                    `(the ":" in the protocol causes a parse error). ` +
+                    `This field uses JSONata Mode — wrap the URL in escaped double quotes: "\\\"${url.trim()}\\\"".`);
+            }
+            else {
+                // If it's a JSONata-quoted string, extract the actual URL for further validation
+                const quotedMatch = url.trim().match(/^"(.*)"$/);
+                const actualUrl = quotedMatch ? quotedMatch[1] : url;
+                try {
+                    const parsed = new URL(actualUrl);
+                    if (parsed.hostname === 'webhook.site' && parsed.pathname === '/') {
+                        warnings.push(`${stepLabel}: URL '${actualUrl}' is the webhook.site homepage, not a unique endpoint. ` +
+                            `Go to https://webhook.site to get a unique URL like https://webhook.site/<unique-id>`);
+                    }
+                    if (parsed.hostname === 'example.com') {
+                        warnings.push(`${stepLabel}: URL '${actualUrl}' points to example.com which is a placeholder domain`);
+                    }
+                }
+                catch {
+                    // Not a valid URL — might be a JSONata expression, which is fine
+                }
+            }
+        }
+    }
+    // 5. Check edges with missing mappers for non-first target steps.
+    // Missing mappers cause empty/red fields in the UI.
+    const edges = flow?.graph?.edges || [];
+    for (const edge of edges) {
+        const edgeId = edge.id || `${edge.source}:${edge.target}`;
+        if (!edge.config?.mapper) {
+            const targetNode = nodes.find((n) => n.id === edge.target);
+            if (targetNode && !targetNode.first) {
+                warnings.push(`Edge '${edgeId}': no mapper configured. Step '${edge.target}' (${targetNode.name || 'unnamed'}) ` +
+                    `will receive no mapped input data, causing empty/red fields in the UI. ` +
+                    `Add a mapper with $getPassthrough() paths for the step's input fields.`);
+            }
+        }
+    }
+    // 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 };
+}
+/** Find action or trigger definition by parsing the command string */
+function findActionOrTrigger(component, command) {
+    if (!command)
+        return null;
+    const match = command.match(/^[^:]+:([^@]+)@/);
+    if (!match)
+        return null;
+    const methodId = match[1];
+    return component.actions?.[methodId] || component.triggers?.[methodId] || null;
+}
+/** 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 ---'];
+    if (result.errors.length > 0) {
+        parts.push(`\nERRORS (${result.errors.length}):`);
+        for (const err of result.errors) {
+            parts.push(`  - ${err}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        parts.push(`\nWARNINGS (${result.warnings.length}):`);
+        for (const warn of result.warnings) {
+            parts.push(`  - ${warn}`);
+        }
+    }
+    if (result.errors.length > 0) {
+        parts.push('\nFix the errors above before starting the flow.');
+    }
+    return parts.join('\n');
+}
+//# sourceMappingURL=validation.js.map