@dypai-ai/mcp 1.0.9 → 1.1.0

package/src/tools/sync/validate.js

@@ -0,0 +1,567 @@
+/**
+ * dypai_validate — static analysis for DYPAI projects (like ESLint for endpoints).
+ *
+ * Catches entire classes of runtime errors BEFORE push:
+ *   - ${input.X} references that don't match the input schema
+ *   - ${nodes.X.Y} references to nodes that don't exist in this endpoint
+ *   - ${current_user_id} / ${current_user_role} used without jwt auth
+ *   - `credential: foo` pointing to a credential that doesn't exist remotely
+ *   - Agent `tools: [foo]` pointing to endpoints that aren't tools
+ *   - SQL queries referencing tables that don't exist in schema.sql
+ *
+ * Returns a list of diagnostics with severity + fix_hint. Non-zero errors
+ * mean push will refuse (unless skip_validation is passed).
+ */
+
+import { readFile } from "fs/promises"
+import { join, resolve as resolvePath } from "path"
+import { fetchRemoteState, readLocalState, readLocalConfig, readLocalRealtime } from "./planner.js"
+
+/**
+ * Validate dypai/realtime.yaml against known schemas/tables. Rules:
+ *   rt_table_not_found — references a table that doesn't exist in schema.sql
+ *   rt_invalid_placeholder — uses a placeholder name outside the allowed set
+ *   rt_invalid_events — events array contains values other than INSERT/UPDATE/DELETE
+ *   rt_empty_target — no tables and no channels declared but realtime.yaml exists
+ */
+async function validateRealtime(rootDir, ctx) {
+  const local = await readLocalRealtime(rootDir)
+  if (!local) return []
+
+  const diagnostics = []
+  const ALLOWED_PLACEHOLDERS = new Set(["current_user_id", "current_user_role", "channel_param"])
+  const ALLOWED_EVENTS = new Set(["INSERT", "UPDATE", "DELETE"])
+
+  if (local.rows.length === 0) {
+    diagnostics.push({
+      severity: "warn",
+      rule: "rt_empty_target",
+      file: "realtime.yaml",
+      message: "realtime.yaml exists but declares no tables or channels.",
+      fix_hint: "Add at least one entry, or delete the file to go back to deny-by-default.",
+    })
+  }
+
+  for (const p of local.rows) {
+    const tag = `${p.target_type}:${p.target_name}`
+
+    // Table must exist in schema.sql
+    if (p.target_type === "table" && ctx.schemaTables && !ctx.schemaTables.has(p.target_name)) {
+      diagnostics.push({
+        severity: "error",
+        rule: "rt_table_not_found",
+        file: "realtime.yaml",
+        loc: `tables.${p.target_name}`,
+        message: `realtime.yaml declares table '${p.target_name}' but it's not in schema.sql.`,
+        fix_hint: `Create the table first (CREATE TABLE public.${p.target_name} ...) or fix the typo.`,
+      })
+    }
+
+    // subscribe_filter placeholders
+    if (p.subscribe_filter) {
+      const placeholderRe = /\$\{([^}]+)\}/g
+      let m
+      while ((m = placeholderRe.exec(p.subscribe_filter)) !== null) {
+        const name = m[1].trim()
+        if (!ALLOWED_PLACEHOLDERS.has(name)) {
+          diagnostics.push({
+            severity: "error",
+            rule: "rt_invalid_placeholder",
+            file: "realtime.yaml",
+            loc: tag,
+            message: `Unknown placeholder \${${name}} in subscribe_filter.`,
+            fix_hint: `Allowed: ${[...ALLOWED_PLACEHOLDERS].map(p => "${" + p + "}").join(", ")}`,
+          })
+        }
+        // channel_param only makes sense for channels with wildcards
+        if (name === "channel_param" && (p.target_type !== "channel" || !p.target_name.includes("%"))) {
+          diagnostics.push({
+            severity: "error",
+            rule: "rt_invalid_placeholder",
+            file: "realtime.yaml",
+            loc: tag,
+            message: `\${channel_param} only resolves on channels with a '%' wildcard in target_name.`,
+            fix_hint: `Use a pattern like 'chat:%' so channel_param captures the variable part.`,
+          })
+        }
+      }
+    }
+
+    // events validation
+    if (Array.isArray(p.events)) {
+      for (const e of p.events) {
+        if (!ALLOWED_EVENTS.has(e)) {
+          diagnostics.push({
+            severity: "error",
+            rule: "rt_invalid_events",
+            file: "realtime.yaml",
+            loc: tag,
+            message: `Invalid event '${e}' in events array.`,
+            fix_hint: `Allowed values: INSERT, UPDATE, DELETE.`,
+          })
+        }
+      }
+    }
+
+    // Perf warning: complex filters (subqueries, JOINs, EXISTS) fall off the
+    // in-memory fast path and hit the DB on every notification. Nudge toward
+    // flat filters when possible.
+    if (p.subscribe_filter && /\b(SELECT|JOIN|EXISTS|UNION|WITH)\b/i.test(p.subscribe_filter)) {
+      diagnostics.push({
+        severity: "warn",
+        rule: "rt_complex_filter",
+        file: "realtime.yaml",
+        loc: tag,
+        message: `Subscribe filter has subqueries/JOINs — each notification will hit the DB.`,
+        fix_hint: `For high-throughput tables, prefer a flat filter (e.g. 'user_id = \${current_user_id}'). If complex is unavoidable, expect ~1-5ms added latency per event.`,
+      })
+    }
+  }
+
+  return diagnostics
+}
+
+/**
+ * Load the node catalog that dypai_pull cached to `dypai/node-catalog.json`.
+ * The catalog is the single source of truth (dumped from public.node_catalog
+ * in the central control plane). If it's missing, the validator falls back
+ * to basic rules — no curated drift-prone JSON here.
+ */
+async function loadNodeCatalog(rootDir) {
+  try {
+    const raw = await readFile(join(rootDir, "node-catalog.json"), "utf8")
+    const parsed = JSON.parse(raw)
+    const schemas = {}
+    const knownTypes = new Set()
+    for (const [nodeType, data] of Object.entries(parsed.nodes || {})) {
+      knownTypes.add(nodeType)
+      schemas[nodeType] = {
+        label: data.label,
+        description: data.description,
+        inputs: data.inputs && Object.keys(data.inputs).length ? data.inputs : null,
+        outputs: data.outputs && Object.keys(data.outputs).length ? data.outputs : null,
+      }
+    }
+    return { schemas, knownTypes, missing: false }
+  } catch {
+    return { schemas: {}, knownTypes: new Set(), missing: true }
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Walk an object, yielding every string value with its JSON path. */
+function* walkStrings(node, path = "") {
+  if (node == null) return
+  if (typeof node === "string") {
+    yield { path, value: node }
+    return
+  }
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      yield* walkStrings(node[i], `${path}[${i}]`)
+    }
+    return
+  }
+  if (typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      yield* walkStrings(v, path ? `${path}.${k}` : k)
+    }
+  }
+}
+
+/** Extract all ${...} placeholder expressions from a string. */
+function extractPlaceholders(s) {
+  const out = []
+  const re = /\$\{([^}]+)\}/g
+  let m
+  while ((m = re.exec(s)) !== null) out.push(m[1])
+  return out
+}
+
+/** Minimal Levenshtein distance, caps at 3 for "did you mean" typo suggestions. */
+function levenshteinSmall(a, b) {
+  if (a === b) return 0
+  if (Math.abs(a.length - b.length) > 3) return 99
+  const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)])
+  for (let j = 0; j <= b.length; j++) m[0][j] = j
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      m[i][j] = Math.min(
+        m[i-1][j] + 1,
+        m[i][j-1] + 1,
+        m[i-1][j-1] + (a[i-1] === b[j-1] ? 0 : 1),
+      )
+    }
+  }
+  return m[a.length][b.length]
+}
+
+/** Parse schema.sql to extract the set of public.<table> names. */
+async function readSchemaTables(rootDir) {
+  try {
+    const raw = await readFile(join(rootDir, "schema.sql"), "utf8")
+    const tables = new Set()
+    const re = /CREATE\s+TABLE\s+public\.(\w+)/gi
+    let m
+    while ((m = re.exec(raw)) !== null) tables.add(m[1])
+    return tables
+  } catch {
+    return null  // schema.sql missing — skip SQL checks
+  }
+}
+
+/** Extract referenced table names from a SQL string: `FROM public.X`, `JOIN public.X`, `INTO public.X`, `UPDATE public.X`. */
+function extractSqlTables(sql) {
+  const tables = new Set()
+  const re = /(?:FROM|JOIN|INTO|UPDATE)\s+public\.(\w+)/gi
+  let m
+  while ((m = re.exec(sql)) !== null) tables.add(m[1])
+  return tables
+}
+
+// ─── Rules ──────────────────────────────────────────────────────────────────
+
+function ruleUsesJwt(trigger) {
+  // current_user_* requires http_api + jwt
+  return trigger?.http_api?.auth_mode === "jwt"
+}
+
+function validateEndpoint(entry, ctx) {
+  const { doc, fileMap } = entry
+  const diagnostics = []
+  const name = doc.name
+  const file = ctx.fileByName[name] || `endpoints/${name}.yaml`
+
+  const inputProps = doc.input?.properties || {}
+  const nodeIds = new Set((doc.workflow?.nodes || []).map(n => n.id))
+
+  const jwt = ruleUsesJwt(doc.trigger)
+
+  // Collect all strings INCLUDING file contents (query_file, system_prompt_file, code_file)
+  const sources = []
+  for (const { path, value } of walkStrings(doc)) {
+    sources.push({ source: "yaml", loc: path, value })
+  }
+  for (const [filePath, content] of Object.entries(fileMap || {})) {
+    sources.push({ source: "file", loc: filePath, value: content })
+  }
+
+  // Collect SQL tables referenced (before checking each individually)
+  const referencedTables = new Set()
+
+  for (const { source, loc, value } of sources) {
+    // --- Placeholder checks ---
+    for (const expr of extractPlaceholders(value)) {
+      // Strip leading/trailing whitespace in the expression
+      const e = expr.trim()
+
+      // ${input.X} or ${input.X.Y}
+      // Only validate against the input schema if one is declared; DYPAI allows
+      // schemaless input (placeholders pass through at runtime), so missing
+      // schema is not an error by itself — at most a WARNING.
+      if (e.startsWith("input.")) {
+        const first = e.slice(6).split(/[.\[]/)[0]
+        const hasSchema = Object.keys(inputProps).length > 0
+        if (hasSchema && !inputProps[first]) {
+          diagnostics.push({
+            severity: "error",
+            rule: "input_placeholder_missing",
+            endpoint: name, file, loc,
+            message: `\${${expr}} references input.${first}, but the endpoint's input schema has no '${first}' property.`,
+            fix_hint: `Valid properties: ${Object.keys(inputProps).join(", ")}`,
+          })
+        } else if (!hasSchema) {
+          // One warning per endpoint max — accumulate in a set
+          ctx.schemaless ??= new Set()
+          if (!ctx.schemaless.has(name)) {
+            ctx.schemaless.add(name)
+            diagnostics.push({
+              severity: "warn",
+              rule: "no_input_schema",
+              endpoint: name, file,
+              message: `This endpoint uses \${input.*} but has no input schema declared.`,
+              fix_hint: `Add an input schema at top level so typos in placeholders can be caught: input: { type: object, properties: { ... } }`,
+            })
+          }
+        }
+      }
+
+      // ${nodes.X.Y}
+      else if (e.startsWith("nodes.")) {
+        const nodeId = e.slice(6).split(/[.\[]/)[0]
+        if (!nodeIds.has(nodeId)) {
+          diagnostics.push({
+            severity: "error",
+            rule: "node_ref_missing",
+            endpoint: name, file, loc,
+            message: `\${${expr}} references node '${nodeId}' but that node is not declared in this workflow.`,
+            fix_hint: nodeIds.size
+              ? `Known nodes: ${[...nodeIds].join(", ")}`
+              : "This endpoint has no nodes yet.",
+          })
+        }
+      }
+
+      // ${current_user_id} / ${current_user_role}
+      else if (e === "current_user_id" || e === "current_user_role") {
+        if (!jwt) {
+          diagnostics.push({
+            severity: "error",
+            rule: "current_user_without_jwt",
+            endpoint: name, file, loc,
+            message: `\${${e}} is only available when the endpoint uses http_api with auth_mode: jwt.`,
+            fix_hint: "Add `trigger: { http_api: { auth_mode: jwt } }` or remove the placeholder.",
+          })
+        }
+      }
+    }
+
+    // --- SQL: collect referenced tables for later comparison against schema.sql ---
+    // Heuristic: look like SQL (contains SELECT/INSERT/UPDATE/DELETE/WITH)
+    if (/\b(SELECT|INSERT|UPDATE|DELETE|WITH)\b/i.test(value)) {
+      for (const t of extractSqlTables(value)) referencedTables.add(t)
+    }
+  }
+
+  // --- SQL table existence (if schema.sql available) ---
+  if (ctx.schemaTables) {
+    for (const table of referencedTables) {
+      if (!ctx.schemaTables.has(table)) {
+        diagnostics.push({
+          severity: "error",
+          rule: "sql_table_not_found",
+          endpoint: name, file,
+          message: `SQL references public.${table}, but that table does not exist in schema.sql.`,
+          fix_hint: `Check typos, or create the table first with execute_sql. Known tables: ${[...ctx.schemaTables].slice(0, 8).join(", ")}${ctx.schemaTables.size > 8 ? "…" : ""}`,
+        })
+      }
+    }
+  }
+
+  // --- Per-node catalog-based validation (unknown type, missing/unknown params) ---
+  for (const node of doc.workflow?.nodes || []) {
+    // node_type exists in catalog?
+    if (ctx.knownTypes.size && !ctx.knownTypes.has(node.type)) {
+      const suggestions = [...ctx.knownTypes].filter(t => levenshteinSmall(t, node.type) <= 2).slice(0, 3)
+      diagnostics.push({
+        severity: "error",
+        rule: "unknown_node_type",
+        endpoint: name, file, loc: `workflow.nodes[${node.id}].type`,
+        message: `Node type '${node.type}' is not registered.`,
+        fix_hint: suggestions.length
+          ? `Did you mean: ${suggestions.join(", ")}?`
+          : `Run dypai_pull to refresh node-catalog.json. Or call search_nodes to discover.`,
+      })
+      continue  // no point checking params of an unknown type
+    }
+
+    // Schema-based parameter validation (only when we have a schema for this node_type)
+    const schema = ctx.catalog[node.type]
+    if (schema?.inputs?.properties) {
+      const { properties, required = [] } = schema.inputs
+      // Ignore node metadata keys (id, type, variable, return, credential, *_file) — they're not "params"
+      const META_KEYS = new Set(["id", "type", "variable", "return", "credential", "query_file", "code_file", "system_prompt_file"])
+      const paramKeys = Object.keys(node).filter(k => !META_KEYS.has(k))
+
+      // Required params present? Severity: warn (not error) because current
+      // engine node_catalog schemas list all conditional params as "required"
+      // (e.g. dypai_database flags `data` AND `query` both required regardless
+      // of `operation`). Once schemas model conditional required properly
+      // (oneOf / dependentRequired), we can bump this back to error.
+      for (const req of required) {
+        if (!paramKeys.includes(req)) {
+          const hasFileEquivalent = META_KEYS.has(`${req}_file`) && node[`${req}_file`]
+          if (!hasFileEquivalent) {
+            diagnostics.push({
+              severity: "warn",
+              rule: "missing_required_param",
+              endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+              message: `Node '${node.id}' (type '${node.type}') may be missing parameter '${req}'.`,
+              fix_hint: `Schema lists required: [${required.join(", ")}]. Verify this param is actually needed for your operation.`,
+            })
+          }
+        }
+      }
+
+      // Unknown/typo params?
+      for (const key of paramKeys) {
+        if (!properties[key]) {
+          const knownKeys = Object.keys(properties)
+          const suggestions = knownKeys.filter(k => levenshteinSmall(k, key) <= 2).slice(0, 2)
+          diagnostics.push({
+            severity: "warn",
+            rule: "unknown_param",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}].${key}`,
+            message: `Node '${node.id}' (type '${node.type}') has unknown parameter '${key}'.`,
+            fix_hint: suggestions.length
+              ? `Did you mean: ${suggestions.join(", ")}?`
+              : `Valid params: ${knownKeys.slice(0, 8).join(", ")}${knownKeys.length > 8 ? "…" : ""}`,
+          })
+        } else {
+          // Enum / range checks for primitive values
+          const prop = properties[key]
+          const v = node[key]
+          if (prop.enum && typeof v === "string" && !prop.enum.includes(v)) {
+            diagnostics.push({
+              severity: "error",
+              rule: "param_enum_violation",
+              endpoint: name, file, loc: `workflow.nodes[${node.id}].${key}`,
+              message: `Node '${node.id}' parameter '${key}' = '${v}' is not one of: ${prop.enum.join(", ")}.`,
+              fix_hint: `Allowed values: ${prop.enum.join(", ")}`,
+            })
+          }
+          if (prop.type === "number" || prop.type === "integer") {
+            if (typeof v === "number") {
+              if (prop.min != null && v < prop.min) {
+                diagnostics.push({
+                  severity: "error",
+                  rule: "param_range_violation",
+                  endpoint: name, file, loc: `workflow.nodes[${node.id}].${key}`,
+                  message: `Node '${node.id}' parameter '${key}' = ${v} is below the minimum ${prop.min}.`,
+                })
+              }
+              if (prop.max != null && v > prop.max) {
+                diagnostics.push({
+                  severity: "error",
+                  rule: "param_range_violation",
+                  endpoint: name, file, loc: `workflow.nodes[${node.id}].${key}`,
+                  message: `Node '${node.id}' parameter '${key}' = ${v} is above the maximum ${prop.max}.`,
+                })
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // --- Credential references ---
+  for (const node of doc.workflow?.nodes || []) {
+    const cred = node.credential
+    if (cred && !ctx.remoteCredentials.has(cred)) {
+      diagnostics.push({
+        severity: "error",
+        rule: "credential_not_found",
+        endpoint: name, file, loc: `workflow.nodes[${node.id}].credential`,
+        message: `credential '${cred}' is not defined remotely.`,
+        fix_hint: ctx.remoteCredentials.size
+          ? `Available: ${[...ctx.remoteCredentials].join(", ")}. Create '${cred}' in the dashboard first.`
+          : "No credentials configured yet. Create one in the dashboard with this exact name.",
+      })
+    }
+
+    // Agent tool references
+    if (node.type === "agent" && Array.isArray(node.tools)) {
+      for (const toolName of node.tools) {
+        if (!ctx.toolEndpoints.has(toolName)) {
+          diagnostics.push({
+            severity: "error",
+            rule: "agent_tool_not_found",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}].tools`,
+            message: `agent references tool '${toolName}' but no endpoint with that name is marked is_tool: true.`,
+            fix_hint: ctx.toolEndpoints.size
+              ? `Available tool endpoints: ${[...ctx.toolEndpoints].join(", ")}`
+              : "No tool endpoints exist yet. Set `tool: true` on the YAML of an existing endpoint to expose it.",
+          })
+        }
+      }
+    }
+  }
+
+  return diagnostics
+}
+
+// ─── Tool ───────────────────────────────────────────────────────────────────
+
+export async function runValidation(rootDir, projectId) {
+  // Load everything in parallel
+  const config = await readLocalConfig(rootDir)
+  const targetProjectId = projectId || config?.project_id || null
+
+  const [local, remote, schemaTables, nodeCatalog] = await Promise.all([
+    readLocalState(rootDir),
+    fetchRemoteState(targetProjectId),
+    readSchemaTables(rootDir),
+    loadNodeCatalog(rootDir),
+  ])
+
+  // Build context for the rules
+  const remoteCredentials = new Set(Object.keys(remote.mapsCtx.credNameToId || {}))
+  // Tool endpoints come from LOCAL YAMLs — the ones marked `tool: true`
+  const toolEndpoints = new Set(
+    Object.values(local.byName)
+      .filter(e => e.doc?.tool === true)
+      .map(e => e.doc.name)
+  )
+
+  const ctx = {
+    remoteCredentials,
+    toolEndpoints,
+    schemaTables,
+    catalog: nodeCatalog.schemas,
+    knownTypes: nodeCatalog.knownTypes,
+    fileByName: Object.fromEntries(Object.values(local.byName).map(e => [e.doc.name, `endpoints/${e.doc.name}.yaml`])),
+  }
+
+  const diagnostics = []
+  for (const entry of Object.values(local.byName)) {
+    diagnostics.push(...validateEndpoint(entry, ctx))
+  }
+
+  // Realtime YAML rules
+  diagnostics.push(...await validateRealtime(rootDir, ctx))
+
+  // Surface any file-read errors too
+  for (const err of local.errors || []) {
+    diagnostics.push({
+      severity: "error",
+      rule: "file_read_error",
+      file: err.file,
+      message: err.error,
+    })
+  }
+
+  const errors = diagnostics.filter(d => d.severity === "error")
+  const warnings = diagnostics.filter(d => d.severity === "warn")
+
+  return {
+    success: errors.length === 0,
+    summary: {
+      total: diagnostics.length,
+      errors: errors.length,
+      warnings: warnings.length,
+      endpoints_checked: Object.keys(local.byName).length,
+      schema_sql_available: schemaTables !== null,
+      node_catalog_nodes: nodeCatalog.knownTypes.size,
+      node_catalog_missing: nodeCatalog.missing,
+      node_catalog_has_schemas: Object.values(nodeCatalog.schemas).some(s => s?.inputs?.properties),
+    },
+    diagnostics,
+  }
+}
+
+export const dypaiValidateTool = {
+  name: "dypai_validate",
+  description:
+    "Lint the local dypai/ folder BEFORE pushing. Catches ${input.x} / ${nodes.x.y} / ${current_user_*} refs that don't resolve, " +
+    "SQL tables not in schema.sql, credentials that don't exist remotely, and agent tool refs to non-tool endpoints. " +
+    "Run this after editing YAMLs to catch typos pre-flight. Push already calls it by default — pass skip_validation:true to override.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_id: { type: "string", description: "Project UUID. Auto-resolved from dypai.config.yaml if omitted." },
+      root_dir: { type: "string", default: "./dypai" },
+    },
+  },
+  async execute({ project_id, root_dir = "./dypai" } = {}) {
+    const rootDir = resolvePath(process.cwd(), root_dir)
+    const result = await runValidation(rootDir, project_id)
+    return {
+      ...result,
+      hint: result.success
+        ? undefined
+        : `${result.summary.errors} error(s) would cause runtime failures. Fix them, or push with skip_validation: true to override (not recommended).`,
+    }
+  },
+}