@elastic.io/mcp 1.0.0-beta

package/dist/tools/validation.js

@@ -0,0 +1,800 @@
+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, 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. ` +
+            `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 [];
+}
+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;
+        }
+        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) {
+            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(/^([^:]+):/);
+            const commandPrefix = prefixMatch ? prefixMatch[1] : '';
+            if (commandPrefix) {
+                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 scoped to component
+            const actionMatch = command.match(/^[^:]+:([^@]+)@/);
+            if (actionMatch && commandPrefix) {
+                const actionId = actionMatch[1];
+                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. ` +
+                        `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 = /^\$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 ` +
+                            `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') {
+        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)) {
+                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') {
+                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) {
+        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".`);
+        }
+    }
+}
+/** 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 = [];
+    const graph = body?.data?.attributes?.graph || body?.attributes?.graph || body?.graph;
+    if (!graph) {
+        return { errors, warnings };
+    }
+    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, warnings };
+    const nodes = graph.nodes || [];
+    const existingComponentIds = new Set();
+    const existingCredSecretIds = new Set();
+    if (existingFlow) {
+        const existingNodes = existingFlow?.graph?.nodes || [];
+        existingNodes.forEach((n) => {
+            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 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)) {
+                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.`);
+        }
+        // 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.`);
+        }
+    }
+    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 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 [...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, 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, 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) {
+            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 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. ` +
+                            `Re-authorize the credential in the UI or replace it with a working one.`);
+                    }
+                }
+                catch (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 {
+                // 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
+                            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.`);
+                    }
+                    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;
+                    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) {
+                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)}`);
+            }
+        }
+        // 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
+                }
+            }
+        }
+        // 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.
+    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.`);
+            }
+        }
+    }
+    return { errors, warnings, stepStatuses };
+}
+/** Find action or trigger definition by parsing the command string */
+function findActionOrTrigger(component, command) {
+    if (!command)
+        return null;
+    const match = /^[^:]+:([^@]+)@/.exec(command);
+    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) {
+    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) {
+            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 && 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');
+}
+//# sourceMappingURL=validation.js.map