@octaviaflow/flow-rules 0.18.0 → 0.19.0

package/dist/index.cjs

@@ -45,7 +45,6 @@ __export(exports_src, {
   ActionStatus: () => ActionStatus,
   ActionType: () => ActionType,
   AggregateConfig: () => AggregateConfig,
-  AggregateFunction: () => AggregateFunction,
   AiAgentConfig: () => AiAgentConfig,
   CONDITION_OPERATORS: () => CONDITION_OPERATORS,
   CONFIG_CONTRACTS: () => CONFIG_CONTRACTS,
@@ -78,19 +77,29 @@ __export(exports_src, {
   GroupConfig: () => GroupConfig,
   IDP_EXTRACT_STRATEGIES: () => IDP_EXTRACT_STRATEGIES,
   IdpExtractConfig: () => IdpExtractConfig,
-  JoinType: () => JoinType,
   JsonActionConfig: () => JsonActionConfig,
-  LogicalOperator: () => LogicalOperator,
   MAPPING_FUNCTIONS: () => MAPPING_FUNCTIONS,
   MAPPING_FUNCTION_SPECS: () => MAPPING_FUNCTION_SPECS,
+  MAX_CONDITION_DEPTH: () => MAX_CONDITION_DEPTH,
   MAX_STEP_CONFIG_BYTES: () => MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig: () => ManualTriggerConfig,
   NodeStatus: () => NodeStatus,
   ONEDRIVE_OPERATIONS: () => ONEDRIVE_OPERATIONS,
   OneDriveActionConfig: () => OneDriveActionConfig,
   PLATFORM_CONFIG_KEYS: () => PLATFORM_CONFIG_KEYS,
+  QUERY_AGGREGATE_FUNCTIONS: () => QUERY_AGGREGATE_FUNCTIONS,
+  QUERY_AUTHORED_SQL_MESSAGE: () => QUERY_AUTHORED_SQL_MESSAGE,
+  QUERY_COMPARISON_OPERATORS: () => QUERY_COMPARISON_OPERATORS,
+  QUERY_CONDITION_OPERATORS: () => QUERY_CONDITION_OPERATORS,
+  QUERY_MODES: () => QUERY_MODES,
+  QUERY_RELATIVE_DATE_OPERATORS: () => QUERY_RELATIVE_DATE_OPERATORS,
+  QUERY_TYPES: () => QUERY_TYPES,
+  QUERY_VISUAL_ONLY_MESSAGE: () => QUERY_VISUAL_ONLY_MESSAGE,
   QueryMode: () => QueryMode,
   QueryType: () => QueryType,
+  RELATIVE_DATE_DIRECTIONS: () => RELATIVE_DATE_DIRECTIONS,
+  RELATIVE_DATE_MAX_AMOUNT: () => RELATIVE_DATE_MAX_AMOUNT,
+  RELATIVE_DATE_UNITS: () => RELATIVE_DATE_UNITS,
   S3ActionConfig: () => S3ActionConfig,
   S3_OPERATIONS: () => S3_OPERATIONS,
   STORAGE_CONNECTOR_IDS: () => STORAGE_CONNECTOR_IDS,
@@ -134,6 +143,7 @@ __export(exports_src, {
   getStorageProvider: () => getStorageProvider,
   groupKeyName: () => groupKeyName,
   inferSchemaFromSample: () => inferSchemaFromSample,
+  isConditionGroup: () => isConditionGroup,
   isEditorPrivateKey: () => isEditorPrivateKey,
   isEventCapableConnector: () => isEventCapableConnector,
   isMappingFunction: () => isMappingFunction,
@@ -141,6 +151,8 @@ __export(exports_src, {
   mappingTransformFunctionName: () => mappingTransformFunctionName,
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
+  queryFieldsSatisfied: () => queryFieldsSatisfied,
+  queryTablesSatisfied: () => queryTablesSatisfied,
   resolveRecordSchema: () => resolveRecordSchema,
   selectsWithoutValues: () => selectsWithoutValues,
   storageConfigKeys: () => storageConfigKeys,
@@ -149,12 +161,14 @@ __export(exports_src, {
   transformConnectionToEdge: () => transformConnectionToEdge,
   transformFlowToWorkflow: () => transformFlowToWorkflow,
   transformStepToNode: () => transformStepToNode,
+  validateBuildQueryConfig: () => validateBuildQueryConfig,
   validateConnectorTriggerEvents: () => validateConnectorTriggerEvents,
   validateEdge: () => validateEdge,
   validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
   validateStepConfig: () => validateStepConfig,
   validateStepConfigs: () => validateStepConfigs,
+  validateVisualConfig: () => validateVisualConfig,
   validateWorkflow: () => validateWorkflow
 });
 module.exports = __toCommonJS(exports_src);
@@ -1183,32 +1197,51 @@ var QueryType;
   QueryType["Delete"] = "delete";
   QueryType["Custom"] = "custom";
 })(QueryType ||= {});
-var LogicalOperator;
-((LogicalOperator) => {
-  LogicalOperator["And"] = "and";
-  LogicalOperator["Or"] = "or";
-})(LogicalOperator ||= {});
+var QUERY_MODES = ["visual" /* Visual */];
+var QUERY_TYPES = ["select" /* Select */];
+var QUERY_COMPARISON_OPERATORS = [
+  "=",
+  "!=",
+  ">",
+  "<",
+  ">=",
+  "<=",
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "lessThan",
+  "greaterOrEqual",
+  "lessOrEqual"
+];
+var QUERY_RELATIVE_DATE_OPERATORS = ["inRelative", "notInRelative"];
+var QUERY_CONDITION_OPERATORS = [
+  ...QUERY_COMPARISON_OPERATORS,
+  "contains",
+  "startsWith",
+  "endsWith",
+  "like",
+  "notLike",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+  ...QUERY_RELATIVE_DATE_OPERATORS
+];
+var RELATIVE_DATE_DIRECTIONS = ["last", "next", "this"];
+var RELATIVE_DATE_UNITS = ["day", "week", "month", "quarter", "year"];
+var RELATIVE_DATE_MAX_AMOUNT = 3650;
+var MAX_CONDITION_DEPTH = 3;
+var isConditionGroup = (c) => !!c && typeof c === "object" && c.type === "group";
+var QUERY_AGGREGATE_FUNCTIONS = ["COUNT", "COUNT_DISTINCT", "SUM", "AVG", "MIN", "MAX"];
 var SortDirection;
 ((SortDirection) => {
   SortDirection["Ascending"] = "asc";
   SortDirection["Descending"] = "desc";
 })(SortDirection ||= {});
-var JoinType;
-((JoinType) => {
-  JoinType["Inner"] = "inner";
-  JoinType["Left"] = "left";
-  JoinType["Right"] = "right";
-  JoinType["Full"] = "full";
-})(JoinType ||= {});
-var AggregateFunction;
-((AggregateFunction) => {
-  AggregateFunction["Count"] = "count";
-  AggregateFunction["Sum"] = "sum";
-  AggregateFunction["Average"] = "avg";
-  AggregateFunction["Min"] = "min";
-  AggregateFunction["Max"] = "max";
-  AggregateFunction["CountDistinct"] = "count_distinct";
-})(AggregateFunction ||= {});
+// src/catalog/isOneOf.ts
+var isOneOf = (set, value) => typeof value === "string" && set.includes(value);
+
 // src/catalog/general/query/config.ts
 var BuildQueryConfigDefaults = {
   mode: "visual" /* Visual */,
@@ -1218,160 +1251,262 @@ var BuildQueryConfigDefaults = {
   visualConfig: {
     tables: [],
     fields: [],
-    filters: undefined,
+    conditions: [],
     joins: [],
     groupBy: [],
+    aggregates: [],
     sort: [],
-    limit: 10,
-    offset: 0
-  },
-  sqlConfig: {
-    sql: "",
-    parameters: {}
+    limit: 10
   }
 };
-var validateBuildQueryConfig = (config) => {
-  const errors = [];
-  const warnings = [];
-  if (!config.connectorId) {
-    errors.push({
-      field: "connectorId",
-      message: "Please select a connector",
-      severity: "error"
-    });
+var QUERY_VISUAL_ONLY_MESSAGE = "The Query step is built with the visual builder only — set mode to 'visual' and describe the query in " + "visualConfig (tables, fields, conditions, sort, groupBy, aggregates). Hand-written SQL is not accepted.";
+var QUERY_AUTHORED_SQL_MESSAGE = "sqlConfig.sql is written by the visual builder, not by hand — remove sqlConfig and describe the query in " + "visualConfig (tables, fields, conditions, sort, groupBy, aggregates) instead.";
+var err = (field, message) => ({ field, message, severity: "error" });
+var isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+var hasValue = (v) => v !== undefined && v !== null && !(typeof v === "string" && v.trim() === "") && !(Array.isArray(v) && v.length === 0);
+var arr = (v) => Array.isArray(v) ? v : [];
+function queryFieldsSatisfied(config) {
+  const vc = isRecord(config?.visualConfig) ? config.visualConfig : undefined;
+  if (!vc)
+    return false;
+  if (vc.selectAll === true)
+    return true;
+  if (arr(vc.fields).length > 0)
+    return true;
+  if (arr(vc.aggregates).length > 0 || arr(vc.groupBy).length > 0)
+    return true;
+  const sql = isRecord(config?.sqlConfig) ? config.sqlConfig.sql : undefined;
+  return arr(vc.tables).length > 0 && nonEmptyString(sql);
+}
+function queryTablesSatisfied(config) {
+  const vc = isRecord(config?.visualConfig) ? config.visualConfig : undefined;
+  if (!vc)
+    return false;
+  return vc.selectAll === true || arr(vc.tables).length > 0;
+}
+var OPERATOR_LIST = QUERY_CONDITION_OPERATORS.join(", ");
+function validateRelative(path, relative) {
+  if (!isRecord(relative)) {
+    return [err(`${path}.relative`, `${path}: a relative-date condition needs relative, e.g. { direction: 'last', amount: 30, unit: 'day' }`)];
   }
-  if (!config.mode) {
-    errors.push({
-      field: "mode",
-      message: "Query mode is required",
-      severity: "error"
-    });
+  const issues = [];
+  const { direction, unit, amount, includeCurrent } = relative;
+  if (!isOneOf(RELATIVE_DATE_DIRECTIONS, direction)) {
+    issues.push(err(`${path}.relative.direction`, `${path}.relative.direction must be one of: ${RELATIVE_DATE_DIRECTIONS.join(", ")} (got "${String(direction)}")`));
   }
-  if (!config.queryType) {
-    errors.push({
-      field: "queryType",
-      message: "Query type is required",
-      severity: "error"
-    });
+  if (!isOneOf(RELATIVE_DATE_UNITS, unit)) {
+    issues.push(err(`${path}.relative.unit`, `${path}.relative.unit must be one of: ${RELATIVE_DATE_UNITS.join(", ")} (got "${String(unit)}")`));
   }
-  if (config.mode === "visual" /* Visual */) {
-    const visualErrors = validateVisualQueryConfig(config.visualConfig);
-    errors.push(...visualErrors);
-  } else if (config.mode === "sql" /* SQL */) {
-    const sqlErrors = validateSQLQueryConfig(config.sqlConfig);
-    errors.push(...sqlErrors);
+  if (direction === "last" || direction === "next") {
+    const ok = typeof amount === "number" && Number.isInteger(amount) && amount >= 1 && amount <= RELATIVE_DATE_MAX_AMOUNT;
+    if (!ok) {
+      issues.push(err(`${path}.relative.amount`, `${path}.relative.amount must be a whole number from 1 to ${RELATIVE_DATE_MAX_AMOUNT} for '${direction}' ` + `(e.g. last 30 days is { direction: 'last', amount: 30, unit: 'day' })`));
+    }
   }
-  if (config.timeout !== undefined) {
-    if (config.timeout < 1000) {
-      errors.push({
-        field: "timeout",
-        message: "Timeout must be at least 1000ms",
-        severity: "error"
-      });
-    } else if (config.timeout > 300000) {
-      warnings.push({
-        field: "timeout",
-        message: "Timeout is very high (>5 minutes)",
-        severity: "warning"
-      });
+  if (includeCurrent !== undefined && typeof includeCurrent !== "boolean") {
+    issues.push(err(`${path}.relative.includeCurrent`, `${path}.relative.includeCurrent must be true or false`));
+  }
+  return issues;
+}
+function validateRow(path, row, inHaving) {
+  const issues = [];
+  if (!nonEmptyString(row.field)) {
+    issues.push(err(`${path}.field`, `${path}: choose the field to compare (field is empty)`));
+  }
+  if (!isOneOf(QUERY_CONDITION_OPERATORS, row.operator)) {
+    issues.push(err(`${path}.operator`, `${path}.operator must be one of: ${OPERATOR_LIST} (got "${String(row.operator)}")`));
+    return issues;
+  }
+  const op = row.operator;
+  const isRelative = isOneOf(QUERY_RELATIVE_DATE_OPERATORS, op);
+  const comparesField = row.valueField !== undefined && row.valueField !== null && row.valueField !== "";
+  if (isRelative) {
+    if (inHaving) {
+      issues.push(err(`${path}.operator`, `${path}: '${op}' filters dates on rows — put it in conditions, not having`));
+    } else {
+      issues.push(...validateRelative(path, row.relative));
+    }
+    if (hasValue(row.value) || comparesField) {
+      issues.push(err(path, `${path}: a relative-date condition takes its window from relative — remove value and valueField`));
     }
+  } else if (row.relative !== undefined) {
+    issues.push(err(`${path}.relative`, `${path}: relative is only used with 'inRelative' or 'notInRelative' — change the operator or remove relative`));
   }
-  if (config.maxRows !== undefined) {
-    if (config.maxRows < 1) {
-      errors.push({
-        field: "maxRows",
-        message: "Max rows must be at least 1",
-        severity: "error"
-      });
-    } else if (config.maxRows > 1e4) {
-      warnings.push({
-        field: "maxRows",
-        message: "Max rows is very high (>10,000). This may impact performance.",
-        severity: "warning"
-      });
+  if (comparesField) {
+    if (inHaving) {
+      issues.push(err(`${path}.valueField`, `${path}: having compares with a value — use value, not valueField`));
+    } else if (!nonEmptyString(row.valueField)) {
+      issues.push(err(`${path}.valueField`, `${path}.valueField must name the field to compare with`));
+    } else if (!isOneOf(QUERY_COMPARISON_OPERATORS, op)) {
+      issues.push(err(`${path}.valueField`, `${path}: comparing with another field works with =, !=, >, <, >=, <= only (got "${op}")`));
+    }
+    if (hasValue(row.value)) {
+      issues.push(err(path, `${path}: set either value (compare with a value) or valueField (compare with another field), not both`));
     }
   }
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings
-  };
-};
-var validateVisualQueryConfig = (config) => {
+  if (row.joinOperator !== undefined && !(typeof row.joinOperator === "string" && /^(and|or)$/i.test(row.joinOperator))) {
+    issues.push(err(`${path}.joinOperator`, `${path}.joinOperator must be AND or OR (got "${String(row.joinOperator)}")`));
+  }
+  return issues;
+}
+function validateConditionList(path, list, depth) {
+  if (list === undefined || list === null)
+    return [];
+  if (!Array.isArray(list))
+    return [err(path, `${path} must be a list of conditions`)];
+  const issues = [];
+  list.forEach((item, i) => {
+    const at = `${path}[${i}]`;
+    if (!isRecord(item)) {
+      issues.push(err(at, `${at} must be a condition ({ field, operator, value }) or a group ({ type: 'group', conditions })`));
+      return;
+    }
+    if (isConditionGroup(item)) {
+      if (depth + 1 > MAX_CONDITION_DEPTH) {
+        issues.push(err(at, `${at}: groups can nest at most ${MAX_CONDITION_DEPTH} levels deep — move this group up a level or combine its conditions`));
+        return;
+      }
+      if (item.joinOperator !== undefined && !(typeof item.joinOperator === "string" && /^(and|or)$/i.test(item.joinOperator))) {
+        issues.push(err(`${at}.joinOperator`, `${at}.joinOperator must be AND or OR (got "${String(item.joinOperator)}")`));
+      }
+      if (!Array.isArray(item.conditions) || item.conditions.length === 0) {
+        issues.push(err(`${at}.conditions`, `${at}: a group needs at least one condition — add one or remove the group`));
+        return;
+      }
+      issues.push(...validateConditionList(`${at}.conditions`, item.conditions, depth + 1));
+      return;
+    }
+    issues.push(...validateRow(at, item, false));
+  });
+  return issues;
+}
+function validateAggregates(vc) {
+  const list = vc.aggregates;
+  if (list === undefined || list === null)
+    return [];
+  if (!Array.isArray(list))
+    return [err("visualConfig.aggregates", "visualConfig.aggregates must be a list of { fn, field, alias }")];
+  const issues = [];
+  list.forEach((a, i) => {
+    const at = `visualConfig.aggregates[${i}]`;
+    if (!isRecord(a)) {
+      issues.push(err(at, `${at} must be { fn, field, alias }`));
+      return;
+    }
+    const fn = typeof a.fn === "string" ? a.fn.toUpperCase() : a.fn;
+    if (!isOneOf(QUERY_AGGREGATE_FUNCTIONS, fn)) {
+      issues.push(err(`${at}.fn`, `${at}.fn must be one of: ${QUERY_AGGREGATE_FUNCTIONS.join(", ")} (got "${String(a.fn)}")`));
+      return;
+    }
+    const allRows = !nonEmptyString(a.field) || a.field.trim() === "*";
+    if (allRows && fn !== "COUNT") {
+      issues.push(err(`${at}.field`, `${at}: ${fn} needs a field to work on — set field to a column name`));
+    }
+    if (a.alias !== undefined && a.alias !== null && !nonEmptyString(a.alias)) {
+      issues.push(err(`${at}.alias`, `${at}.alias must be a name for the result column, or left out`));
+    }
+  });
+  return issues;
+}
+function validateHaving(vc) {
+  const list = vc.having;
+  if (list === undefined || list === null || Array.isArray(list) && list.length === 0)
+    return [];
+  if (!Array.isArray(list))
+    return [err("visualConfig.having", "visualConfig.having must be a list of conditions")];
+  const aggregates = arr(vc.aggregates).filter(isRecord);
+  const groupBy = arr(vc.groupBy).filter(nonEmptyString);
+  if (aggregates.length === 0 && groupBy.length === 0) {
+    return [err("visualConfig.having", "visualConfig.having filters grouped results, so it needs aggregates or groupBy — add them, or move these filters to conditions")];
+  }
+  const names = new Set([
+    ...groupBy,
+    ...aggregates.map((a) => a.alias).filter(nonEmptyString)
+  ]);
+  const issues = [];
+  list.forEach((row, i) => {
+    const at = `visualConfig.having[${i}]`;
+    if (!isRecord(row) || isConditionGroup(row)) {
+      issues.push(err(at, `${at} must be a single condition ({ field, operator, value }); groups are not used in having`));
+      return;
+    }
+    issues.push(...validateRow(at, row, true));
+    if (nonEmptyString(row.field) && !names.has(row.field)) {
+      const known = [...names];
+      issues.push(err(`${at}.field`, `${at}.field must be an aggregate alias or a groupBy column (got "${row.field}"` + (known.length > 0 ? `; available: ${known.join(", ")})` : "; give the aggregate an alias first)")));
+    }
+  });
+  return issues;
+}
+function validateVisualConfig(config) {
+  const vc = config.visualConfig;
+  if (!isRecord(vc)) {
+    return [err("visualConfig", "visualConfig is required — describe the query with tables (what to read), fields (which columns) and optional conditions")];
+  }
+  const issues = [];
+  if (!queryTablesSatisfied(config)) {
+    issues.push(err("visualConfig.tables", "At least one table must be selected (visualConfig.tables)"));
+  }
+  if (!queryFieldsSatisfied(config)) {
+    issues.push(err("visualConfig.fields", "At least one field must be selected (visualConfig.fields), or add aggregates / groupBy for a summary query"));
+  }
+  if (arr(vc.tables).length > 1 && arr(vc.joins).length === 0) {
+    issues.push(err("visualConfig.joins", "Joins are required when selecting from multiple tables (visualConfig.joins)"));
+  }
+  if (vc.distinct !== undefined && typeof vc.distinct !== "boolean") {
+    issues.push(err("visualConfig.distinct", "visualConfig.distinct must be true or false"));
+  }
+  issues.push(...validateConditionList("visualConfig.conditions", vc.conditions, 0));
+  issues.push(...validateAggregates(vc));
+  issues.push(...validateHaving(vc));
+  return issues;
+}
+var validateBuildQueryConfig = (config) => {
+  const c = config;
   const errors = [];
-  if (!config) {
-    errors.push({
-      field: "visualConfig",
-      message: "Visual query configuration is required",
-      severity: "error"
-    });
-    return errors;
+  const warnings = [];
+  if (!c.connectorId) {
+    errors.push(err("connectorId", "Please select a connector (connectorId)"));
   }
-  if (!config.tables || config.tables.length === 0) {
-    errors.push({
-      field: "visualConfig.tables",
-      message: "At least one table must be selected",
-      severity: "error"
-    });
+  const mode = c.mode;
+  const visual = mode === undefined || mode === null || mode === "" || isOneOf(QUERY_MODES, mode);
+  if (!visual) {
+    errors.push(err("mode", `Mode must be one of: ${QUERY_MODES.join(", ")} (got "${String(mode)}"). ${QUERY_VISUAL_ONLY_MESSAGE}`));
+  } else if (!mode) {
+    errors.push(err("mode", "Query mode is required — set mode to 'visual'"));
   }
-  if (!config.fields || config.fields.length === 0) {
-    errors.push({
-      field: "visualConfig.fields",
-      message: "At least one field must be selected",
-      severity: "error"
-    });
+  const queryType = c.queryType;
+  if (!queryType) {
+    errors.push(err("queryType", "Query type is required — set queryType to 'select'"));
+  } else if (!isOneOf(QUERY_TYPES, queryType)) {
+    errors.push(err("queryType", `Query type must be one of: ${QUERY_TYPES.join(", ")} (got "${String(queryType)}"). ` + "The Query step only reads data — use a Transform step to insert, update or delete."));
   }
-  if (config.tables && config.tables.length > 1) {
-    if (!config.joins || config.joins.length === 0) {
-      errors.push({
-        field: "visualConfig.joins",
-        message: "Joins are required when selecting from multiple tables",
-        severity: "error"
-      });
+  if (visual) {
+    const sql = isRecord(c.sqlConfig) ? c.sqlConfig.sql : undefined;
+    if (nonEmptyString(sql) && !isRecord(c.visualConfig)) {
+      errors.push(err("sqlConfig.sql", QUERY_AUTHORED_SQL_MESSAGE));
+    } else {
+      errors.push(...validateVisualConfig(c));
     }
   }
-  const hasAggregates = config.fields?.some((field) => field.aggregate);
-  const hasNonAggregates = config.fields?.some((field) => !field.aggregate);
-  if (hasAggregates && hasNonAggregates) {
-    if (!config.groupBy || config.groupBy.length === 0) {
-      errors.push({
-        field: "visualConfig.groupBy",
-        message: "Group by is required when mixing aggregate and non-aggregate fields",
-        severity: "error"
-      });
+  const timeout = c.timeout;
+  if (typeof timeout === "number") {
+    if (timeout < 1000) {
+      errors.push(err("timeout", "Timeout must be at least 1000ms"));
+    } else if (timeout > 300000) {
+      warnings.push({ field: "timeout", message: "Timeout is very high (>5 minutes)", severity: "warning" });
     }
   }
-  return errors;
-};
-var validateSQLQueryConfig = (config) => {
-  const errors = [];
-  if (!config) {
-    errors.push({
-      field: "sqlConfig",
-      message: "SQL query configuration is required",
-      severity: "error"
-    });
-    return errors;
-  }
-  if (!config.sql || config.sql.trim().length === 0) {
-    errors.push({
-      field: "sqlConfig.sql",
-      message: "SQL query is required",
-      severity: "error"
-    });
-  } else {
-    const sql = config.sql.trim().toLowerCase();
-    const dangerousKeywords = ["drop", "truncate", "alter", "create", "grant", "revoke"];
-    const hasDangerousKeyword = dangerousKeywords.some((keyword) => sql.includes(keyword + " "));
-    if (hasDangerousKeyword) {
-      errors.push({
-        field: "sqlConfig.sql",
-        message: "SQL query contains potentially dangerous operations (DROP, TRUNCATE, ALTER, etc.)",
-        severity: "error"
-      });
+  const maxRows = c.maxRows;
+  if (typeof maxRows === "number") {
+    if (maxRows < 1) {
+      errors.push(err("maxRows", "Max rows must be at least 1"));
+    } else if (maxRows > 1e4) {
+      warnings.push({ field: "maxRows", message: "Max rows is very high (>10,000). This may impact performance.", severity: "warning" });
     }
   }
-  return errors;
+  return { valid: errors.length === 0, errors, warnings };
 };
 function isQueryableConnector(connector) {
   if (connector.isQueryable !== undefined) {
@@ -1403,17 +1538,26 @@ var BuildQueryContractSchema = {
   mode: {
     type: "select",
     required: true,
-    options: ["visual", "sql"],
-    description: "visual: the query is built from visualConfig; sql: the query is the text in sqlConfig.sql"
+    options: QUERY_MODES,
+    description: "Always 'visual': the Query step is built with the visual builder and described in visualConfig. Hand-written SQL is not accepted."
   },
   queryType: {
     type: "select",
     required: true,
-    options: ["select", "insert", "update", "delete", "custom"],
-    description: "Only select is a read; the write types exist for the SQL mode of database connectors"
+    options: QUERY_TYPES,
+    description: "Always 'select': the Query step reads data. Use a Transform step to write."
+  },
+  visualConfig: {
+    type: "object",
+    required: false,
+    description: 'The query. tables: the table or object to read; fields: "table.column" names to return; ' + "conditions: filters { field, operator, value } (or valueField to compare two fields, or operator " + "'inRelative' with relative { direction: last|next|this, amount, unit: day|week|month|quarter|year } for date windows), " + `which may be grouped { type: 'group', conditions } up to ${MAX_CONDITION_DEPTH} levels deep and joined with AND/OR; ` + "distinct; groupBy; aggregates [{ fn: COUNT|COUNT_DISTINCT|SUM|AVG|MIN|MAX, field, alias }]; " + "having: filters on aggregate aliases or groupBy columns; sort [{ field, direction }]; maxRows: the run cap (up to 10,000)."
+  },
+  sqlConfig: {
+    type: "object",
+    required: false,
+    derived: true,
+    description: "Compiled from visualConfig by the editor or the server. Never write it — describe the query in visualConfig."
   },
-  visualConfig: { type: "object", required: false },
-  sqlConfig: { type: "object", required: false },
   timeout: { type: "number", required: false },
   maxRows: { type: "number", required: false }
 };
@@ -1422,11 +1566,11 @@ var BuildQueryContractSchema = {
 var queryDefinition = {
   id: "query",
   name: "Query",
-  description: "Execute queries against connected databases, APIs, and CRMs",
-  longDescription: "Create powerful queries using either a visual no-code builder or advanced SQL editor. Supports databases (PostgreSQL, MySQL, MongoDB, etc.), APIs (REST, GraphQL), and CRMs (Salesforce, HubSpot). Query results can be used as input for downstream actions.",
+  description: "Read records from a connected database, app or CRM",
+  longDescription: "Pick a table or object, the fields you want and any filters, and the Query step reads the matching records. Filters can be grouped with AND / OR, compare two fields, or use a date window such as the last 30 days. You can also remove duplicates, count, total or average values by group, filter those totals, and sort the result. Works with databases (PostgreSQL, MySQL, SQL Server, MongoDB and more), apps (QuickBooks, HubSpot, Jira, Shopify, Google Sheets and more) and CRMs (Salesforce). The records it returns can be used by the steps that follow.",
   category: "database" /* Database */,
   type: "query" /* Query */,
-  tags: ["query", "database", "sql", "visual-builder", "no-code", "api", "crm", "built-in"],
+  tags: ["query", "database", "visual-builder", "no-code", "filter", "api", "crm", "built-in"],
   status: "stable" /* Stable */,
   icon: "QueryQueue",
   color: "#0043ce",
@@ -1444,17 +1588,12 @@ var queryDefinition = {
         key: "mode",
         label: "Query Mode",
         type: "select" /* Select */,
-        description: "Choose between visual query builder or SQL editor",
+        description: "Always 'visual' — the query is built with the visual builder",
         options: [
           {
-            label: "Visual Builder (No-Code)",
+            label: "Visual Builder",
             value: "visual" /* Visual */,
-            description: "Build queries visually without writing code"
-          },
-          {
-            label: "SQL Editor (Advanced)",
-            value: "sql" /* SQL */,
-            description: "Write raw SQL queries with syntax highlighting"
+            description: "Pick the table, fields and filters — no code needed"
           }
         ],
         defaultValue: "visual" /* Visual */,
@@ -1502,7 +1641,7 @@ var queryDefinition = {
         key: "visualConfig.fields",
         label: "Select Fields",
         type: "array" /* Array */,
-        description: "Choose fields to include in the query result",
+        description: 'The fields to return, as "table.column". Not needed for a summary query (aggregates / groupBy) or when every table and field is selected.',
         validation: { required: true },
         conditional: [
           {
@@ -1545,39 +1684,6 @@ var queryDefinition = {
           }
         ]
       },
-      {
-        key: "sqlConfig.sql",
-        label: "SQL Query",
-        type: "code" /* Code */,
-        language: "sql",
-        description: "Write your SQL query here",
-        placeholder: "SELECT * FROM users WHERE status = 'active' LIMIT 100",
-        validation: { required: true },
-        conditional: [
-          {
-            field: "mode",
-            operator: "==",
-            value: "sql" /* SQL */,
-            action: "show"
-          }
-        ]
-      },
-      {
-        key: "sqlConfig.parameters",
-        label: "Query Parameters",
-        type: "json" /* JSON */,
-        description: 'Parameters for parameterized queries (e.g., {"userId": 123})',
-        validation: { required: false },
-        advanced: true,
-        conditional: [
-          {
-            field: "mode",
-            operator: "==",
-            value: "sql" /* SQL */,
-            action: "show"
-          }
-        ]
-      },
       {
         key: "timeout",
         label: "Query Timeout (ms)",
@@ -1591,7 +1697,7 @@ var queryDefinition = {
         key: "maxRows",
         label: "Max Rows",
         type: "number" /* Number */,
-        description: "Legacy step-level field — NOT read at run. Cap a visual Query with visualConfig.maxRows; in SQL mode write a LIMIT.",
+        description: "Legacy step-level field — not read at run. To cap a run, set visualConfig.maxRows.",
         defaultValue: 1000,
         validation: { required: false, min: 1, max: 1e4 },
         advanced: true
@@ -1607,7 +1713,7 @@ var queryDefinition = {
       {
         id: "query_mode",
         label: "Query Configuration",
-        description: "Configure how you want to build your query",
+        description: "The query is built with the visual builder",
         fields: ["mode", "queryType"]
       },
       {
@@ -1616,12 +1722,6 @@ var queryDefinition = {
         description: "Build your query visually without writing code",
         fields: ["visualConfig.tables", "visualConfig.fields", "visualConfig.limit"]
       },
-      {
-        id: "sql_editor",
-        label: "SQL Editor",
-        description: "Write raw SQL queries",
-        fields: ["sqlConfig.sql", "sqlConfig.parameters"]
-      },
       {
         id: "settings",
         label: "Advanced Settings",
@@ -1661,7 +1761,7 @@ var queryDefinition = {
       {
         key: "generatedSQL",
         type: "string" /* String */,
-        description: "The SQL query that was executed (for visual builder mode)",
+        description: "The query that ran, compiled from the visual builder",
         example: "SELECT id, name, email FROM users WHERE status = 'active' LIMIT 100"
       }
     ],
@@ -2856,6 +2956,10 @@ function isSatisfiedOutOfBand(actionId, fieldKey, config) {
       return true;
     return Array.isArray(config.blocks) && config.blocks.length > 0;
   }
+  if (actionId === "query" && fieldKey === "visualConfig.fields")
+    return queryFieldsSatisfied(config);
+  if (actionId === "query" && fieldKey === "visualConfig.tables")
+    return queryTablesSatisfied(config);
   return false;
 }
 var MESSAGE_BODY_ACTIONS = new Set([
@@ -3750,9 +3854,6 @@ var EmailConfig = {
     }
   }
 };
-// src/catalog/isOneOf.ts
-var isOneOf = (set, value) => typeof value === "string" && set.includes(value);
-
 // src/catalog/general/transform/config.ts
 var TRANSFORM_MODES = ["visual", "expression"];
 var TRANSFORM_OPERATIONS = [