@dypai-ai/mcp 1.5.19 → 1.5.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.5.19",
+  "version": "1.5.23",
   "description": "DYPAI MCP Server — AI agent toolkit for building and deploying full-stack apps",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -35,10 +35,7 @@ import { manageFrontendTool } from "./tools/frontend.js"
 // import { scaffoldTool } from "./tools/scaffold.js"
 import { manageDomainTool } from "./tools/domains.js"
 import { bulkUpsertTool } from "./tools/bulk-upsert.js"
-import {
-  searchCapabilityKitsTool,
-  manageCapabilityKitTool,
-} from "./tools/capability-kits.js"
+import { manageProjectArtifactTool } from "./tools/project-artifacts.js"
 import { uploadFile } from "./tools/storage.js"
 // dypaiTestTool (YAML test-suite runner) is intentionally not imported — deferred to v2.
 // The format works but needs fixtures/auto-rollback/scaffolder + proper docs before being surfaced.
@@ -86,9 +83,8 @@ const LOCAL_TOOLS = [
   manageDomainTool,
   // ── Data ──────────────────────────────────────────────────────────────────
   bulkUpsertTool,
-  // ── Capability kits (local source installer) ──────────────────────────────
-  searchCapabilityKitsTool,
-  manageCapabilityKitTool,
+  // ── Project artifacts (install via cloud GitHub fetch + local workspace copy) ──
+  manageProjectArtifactTool,
   // ── Git-first source of truth ─────────────────────────────────────────────
   // dypai_describe was merged into dypai_pull (now returns an `overview` block).
   dypaiPullTool,
@@ -494,6 +490,34 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
 
   // ── Knowledge ─────────────────────────────────────────────────────────────
   { name: "search_docs", description: "Search DYPAI documentation. Use this when unsure about SDK usage, auth patterns, workflow nodes, or platform features. Returns relevant documentation chunks.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What you want to learn about" } }, required: ["query"] } },
+  {
+    name: "search_project_artifacts",
+    description: "Search installable project shells and feature modules from the unified dytemplates catalog (semantic). Returns shells, vertical features, and reusable modules (often kit-* slugs). Use before install via manage_project_artifact.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural language need, e.g. 'calendario de reservas para hotel'." },
+        surface: { type: "string", enum: ["public", "private", "mixed", "agnostic"], description: "Filter by surface; agnostic modules always match when set." },
+        kind: { type: "string", enum: ["shell", "feature"], description: "Restrict to shells or feature modules." },
+        compatible_shell: { type: "string", description: "Shell slug; returns features compatible with it." },
+        limit: { type: "integer", default: 20, minimum: 1, maximum: 50 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "fetch_project_artifact",
+    description: "Download artifact source from GitHub (server-side). Requires source_repo, source_path, source_ref from search_project_artifacts. Used internally by manage_project_artifact; agents normally call manage_project_artifact only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_repo: { type: "string", description: "e.g. dyapps-codes/artifacts" },
+        source_path: { type: "string", description: "e.g. kits/pricing-stripe" },
+        source_ref: { type: "string", default: "main" },
+      },
+      required: ["source_repo"],
+    },
+  },
   { name: "search_design_patterns", description: "Search compact DYPAI UI/design recipes. Use before designing substantial screens.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Design need, with starter/domain/screen/style context when known." }, starter_slug: { type: "string", description: "Optional: private-admin, user-accounts, landing-admin, or blank." }, app_type: { type: "string", description: "Optional domain/app type." }, screen_type: { type: "string", description: "Optional screen/workflow." }, visual_style: { type: "string", description: "Optional style." }, category: { type: "string", description: "Optional category." }, limit: { type: "integer", default: 3, minimum: 1, maximum: 4 } }, required: ["query"] } },
   { name: "search_workflow_templates", description: "Search workflow templates by description. Returns ready-to-use workflow code for common patterns: CRUD operations, payment gateways, email sending, AI chatbots, data pipelines, etc.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What the workflow should do (e.g. 'send email', 'stripe payment')" }, category: { type: "string", description: "Optional: AI, Database, Payments, Communication, Logic, Storage" } }, required: ["query"] } },
   { name: "search_project_templates", description: "Search visible DYPAI Studio project templates by description. Returns only the Studio catalog plus compact template briefs and selection_guidance: recommended_slug, confidence, fallback_slug, and agent_rule.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What kind of project starter you need, in the user's language (e.g. 'app para barberia con reservas', 'private admin dashboard', 'landing plus admin')" }, category: { type: "string", description: "Optional category/type filter." }, limit: { type: "integer", default: 5, minimum: 1, maximum: 10 }, include_drafts: { type: "boolean", default: false, description: "Internal/local testing only. Include draft Studio catalog templates." } }, required: ["query"] } },
@@ -544,16 +568,13 @@ forms, calendars, or domain-specific screens), use \`search_design_patterns\`
 with the app/starter/screen/style context. It returns curated recipes; adapt
 them to the project instead of inventing generic starter UI.
 
-For complex reusable capabilities (calendar booking, interactive maps, CRUD
-tables, Kanban boards, upload/document flows, dashboards, rich editors), also
-use \`search_capability_kits\`. If a strong kit matches, inspect it with
-\`manage_capability_kit(operation: "inspect")\` and install it with
-\`manage_capability_kit(operation: "apply")\` instead of building that complex
-component from scratch. Installed kit code is editable workspace source; after
-install, if the tool returns dependencies, add any missing packages to the
-target workspace package.json and install them locally (never globally or in
-the MCP server). Then wire the kit into the app, apply SQL if needed, validate
-endpoints, and verify the frontend.
+For shells, vertical features, and reusable modules (calendar, maps, CRUD tables,
+Kanban, uploads, dashboards, editors), use \`search_project_artifacts\` first.
+If an artifact fits, pass the exact \`slug\` from the search hit into
+\`manage_project_artifact(operation: "inspect")\` then \`operation: "apply"\`
+instead of building that complex slice from scratch. Installed artifact code is
+editable workspace source; add missing deps to package.json locally, apply SQL
+with execute_sql when needed, validate endpoints, and verify the frontend.
 
 **The template system exists to save time when the fit is obvious, not to force-match every request.** When in doubt → use the safest returned Studio base. Iterating up from a smaller base is cheaper than deleting 80% of a mismatched template.
 
@@ -1036,7 +1057,7 @@ Endpoint naming is strict: the YAML \`name\` is the public API slug and must exa
 
 Mental translations: "edge function" → workflow with one code node; "cron" → \`trigger.schedule\` in the YAML; "webhook receiver" → \`trigger.webhook\`; "internal API" → \`trigger.http_api auth_mode:jwt\`.
 
-→ Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
+→ Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Public HTTP response vs internal node output: \`search_docs("placeholder cheatsheet")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
 
 ## What the engine handles for you (don't reinvent)
 
@@ -1057,9 +1078,10 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 3. **Treating \`dypai_push\` as a deploy** — it's "save as draft", not publish. Live traffic is untouched until \`manage_drafts(publish, confirm:true)\`. Push freely, only ask the user before publish.
 4. **\`public\` auth_mode with \`\${current_user_id}\`** — no JWT → placeholder empty → SQL fails or returns wrong data. Use \`jwt\` if you need the user.
 5. **Missing \`return: true\`** — endpoint returns \`null\`. Every path that should produce an HTTP response needs one node with \`return: true\`.
-6. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
-7. **Putting workflow placeholders inside \`javascript_code.code\`** — code is raw JavaScript, so JS template literals like \`\${where.join(" AND ")}\` are safe and not rendered by DYPAI. Pass workflow values via \`input_data\`, \`ctx.nodes\`, \`ctx.user\`, or \`ctx.env\`; do not write \`\${input.email}\` inside code or set \`code\` from another node output.
-8. **Human endpoint names** — \`name: Listar videos\` in \`list-videos.yaml\` creates a draft the frontend cannot call as \`list-videos\`. \`dypai_validate\` and \`dypai_push\` reject this; fix the slug instead of testing around it.
+6. **SQL return + \`output.type: object\` without \`response_cardinality\` or \`set_fields\`** — runtime body is \`[{...}]\` but the frontend expects \`{...}\`. Add top-level \`response_cardinality: single\` for direct SQL returns, or compose the public object with \`set_fields\`. \`dypai_validate\` errors with \`response_cardinality_required\`. Do not unwrap arrays in frontend code.
+7. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
+8. **Putting workflow placeholders inside \`javascript_code.code\`** — code is raw JavaScript, so JS template literals like \`\${where.join(" AND ")}\` are safe and not rendered by DYPAI. Pass workflow values via \`input_data\`, \`ctx.nodes\`, \`ctx.user\`, or \`ctx.env\`; do not write \`\${input.email}\` inside code or set \`code\` from another node output.
+9. **Human endpoint names** — \`name: Listar videos\` in \`list-videos.yaml\` creates a draft the frontend cannot call as \`list-videos\`. \`dypai_validate\` and \`dypai_push\` reject this; fix the slug instead of testing around it.
 
 → Longer list of common pitfalls + fixes: \`search_docs("troubleshooting")\`.
 
@@ -1080,7 +1102,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 
 SDK is pre-configured at \`src/lib/dypai.ts\` (or \`src/dypai.ts\`). Import \`dypai\` from there. Every method returns \`{ data, error }\` — never throws.
 
-- **API**: \`dypai.api.get(name)\`, \`.post(name, body)\`, \`.put()\`, \`.delete()\`, \`.upload(name, file)\`, \`.stream(name, body)\`.
+- **API**: \`dypai.api.get(name)\`, \`.post(name, body)\`, \`.put()\`, \`.delete()\`, \`.upload(name, file)\`, \`.stream(name, body)\`. \`response.data\` matches the endpoint \`output\` schema — if SQL returns row arrays, declare \`response_cardinality: single\` or use \`set_fields\`; never unwrap in the UI.
 - **Auth**: \`dypai.auth.signInWithPassword()\`, \`.signUp()\`, \`.signOut()\`, \`.getSession()\`. **Never** create login/signup workflows — auth is built-in.
 - **Hooks**: \`useAuth\`, \`useEndpoint\`, \`useAction\`, \`useUpload\`, \`useRealtime\`, \`<ProtectedRoute>\`.
 - **Rule**: NEVER \`fetch()\` directly — always through the SDK.
@@ -1121,7 +1143,7 @@ async function handleRequest(msg) {
     return makeResponse(id, {
       protocolVersion: "2024-11-05",
       capabilities: { tools: {} },
-      serverInfo: { name: "dypai", version: "1.5.14" },
+      serverInfo: { name: "dypai", version: "1.5.23" },
       instructions: SERVER_INSTRUCTIONS,
     })
   }

package/src/lib/workflow-placeholder-contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Canonical workflow placeholder / SQL cardinality helpers.
+ * Copy into workspace/engine — do not import across service deploy boundaries.
+ */
+
+export type SqlCardinality = "single" | "many" | null;
+
+export type PlaceholderDiagnostic = {
+  rule: string;
+  message: string;
+  fix_hint: string;
+  example_fix?: string;
+};
+
+export function stripSqlForInference(sqlText: string): string;
+
+export function hasTopLevelLimitOne(sqlText: string): boolean;
+
+export function inferSqlCardinality(sqlText: string): SqlCardinality;
+
+/** Alias: true when inferSqlCardinality returns "single". */
+export function sqlProvesSingleRow(sqlText: string): boolean;
+
+/**
+ * Parse node id from nodes.* expression; supports bracket index.
+ * nodes.foo[0].bar → "foo"
+ */
+export function referencedNodeIdFromNodesExpression(expr: string): string | null;
+
+export function stripePlaceholderIssue(
+  placeholder: string,
+  nodeId: string,
+  nodeType: string,
+): PlaceholderDiagnostic | null;
+
+export function databaseManyRowPlaceholderIssue(
+  placeholder: string,
+  nodeId: string,
+  cardinality: SqlCardinality | "single" | "many",
+): PlaceholderDiagnostic | null;
+
+export function outputSchemaPropertyNames(outputSchema: unknown): Set<string>;
+
+export function workflowOutputKeys(workflowOutput: unknown): Set<string>;
+
+/** Keys present in workflow.output but missing from output.properties. */
+export function workflowOutputMismatchKeys(
+  outputSchema: unknown,
+  workflowOutput: unknown,
+): string[];

package/src/lib/workflow-placeholder-contract.js

@@ -0,0 +1,364 @@
+/**
+ * Canonical workflow placeholder / SQL cardinality helpers for DYPAI validators.
+ *
+ * Source of truth for MCP (`dypai_validate`). Copy into other services (workspace,
+ * engine-side tooling) — do NOT import this file across service boundaries at runtime.
+ *
+ * @see test-fixtures/workflow-contract/ for golden parity checks
+ */
+
+const AGGREGATE_FUNCTIONS = [
+  "count",
+  "sum",
+  "avg",
+  "min",
+  "max",
+  "json_agg",
+  "jsonb_agg",
+  "array_agg",
+  "string_agg",
+];
+
+export function stripSqlForInference(sqlText) {
+  return String(sqlText || "")
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function isWordAt(sql, index, word) {
+  if (sql.slice(index, index + word.length).toLowerCase() !== word) return false;
+  const before = index === 0 ? "" : sql[index - 1];
+  const after = sql[index + word.length] || "";
+  return !/[A-Za-z0-9_]/.test(before) && !/[A-Za-z0-9_]/.test(after);
+}
+
+function skipDoubleQuotedIdentifier(sql, index) {
+  if (sql[index] !== '"') return index;
+  for (let i = index + 1; i < sql.length; i++) {
+    if (sql[i] !== '"') continue;
+    if (sql[i + 1] === '"') {
+      i++;
+      continue;
+    }
+    return i;
+  }
+  return sql.length - 1;
+}
+
+function skipSqlSpaces(sql, index) {
+  let i = index;
+  while (i < sql.length && /\s/.test(sql[i])) i++;
+  return i;
+}
+
+function findMatchingParen(sql, openIndex) {
+  if (sql[openIndex] !== "(") return -1;
+  let depth = 0;
+  for (let i = openIndex; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function findOuterSelectList(sqlText) {
+  const sql = stripSqlForInference(sqlText);
+  if (!sql) return null;
+  let depth = 0;
+  let selectStart = -1;
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") depth++;
+    else if (ch === ")") depth = Math.max(0, depth - 1);
+
+    if (depth !== 0) continue;
+    if (selectStart < 0 && isWordAt(sql, i, "select")) {
+      selectStart = i + "select".length;
+      i += "select".length - 1;
+      continue;
+    }
+    if (selectStart >= 0 && isWordAt(sql, i, "from")) {
+      return sql.slice(selectStart, i).trim();
+    }
+  }
+  if (selectStart >= 0) return sql.slice(selectStart).trim();
+  return null;
+}
+
+export function hasTopLevelLimitOne(sqlText) {
+  const sql = stripSqlForInference(sqlText);
+  let depth = 0;
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth !== 0 || !isWordAt(sql, i, "limit")) continue;
+    const tail = sql.slice(skipSqlSpaces(sql, i + "limit".length));
+    if (/^1(?:\D|$)/.test(tail)) return true;
+  }
+  return false;
+}
+
+function hasTopLevelFetchOne(sqlText) {
+  const sql = stripSqlForInference(sqlText);
+  let depth = 0;
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth !== 0 || !isWordAt(sql, i, "fetch")) continue;
+
+    let cursor = skipSqlSpaces(sql, i + "fetch".length);
+    if (isWordAt(sql, cursor, "first")) cursor += "first".length;
+    else if (isWordAt(sql, cursor, "next")) cursor += "next".length;
+    else continue;
+    cursor = skipSqlSpaces(sql, cursor);
+    if (/^1(?:\D|$)/.test(sql.slice(cursor))) return true;
+  }
+  return false;
+}
+
+function hasTopLevelGroupBy(sqlText) {
+  const sql = stripSqlForInference(sqlText);
+  let depth = 0;
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth !== 0 || !isWordAt(sql, i, "group")) continue;
+
+    const restStart = i + "group".length;
+    const rest = sql.slice(restStart);
+    const byOffset = rest.search(/\S/);
+    if (byOffset >= 0 && isWordAt(sql, restStart + byOffset, "by")) return true;
+  }
+  return false;
+}
+
+function hasTopLevelSetOperation(sqlText) {
+  const sql = stripSqlForInference(sqlText);
+  let depth = 0;
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth !== 0) continue;
+    if (isWordAt(sql, i, "union") || isWordAt(sql, i, "intersect") || isWordAt(sql, i, "except")) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isWindowAggregateCall(sql, openIndex) {
+  const closeIndex = findMatchingParen(sql, openIndex);
+  if (closeIndex < 0) return false;
+
+  let cursor = skipSqlSpaces(sql, closeIndex + 1);
+  if (isWordAt(sql, cursor, "filter")) {
+    cursor = skipSqlSpaces(sql, cursor + "filter".length);
+    if (sql[cursor] === "(") {
+      const filterClose = findMatchingParen(sql, cursor);
+      if (filterClose >= 0) cursor = skipSqlSpaces(sql, filterClose + 1);
+    }
+  }
+
+  return isWordAt(sql, cursor, "over");
+}
+
+function hasOuterAggregateFunction(selectList) {
+  const sql = String(selectList || "");
+  let depth = 0;
+  const activeSubqueryDepths = [];
+
+  const insideSubquery = () => activeSubqueryDepths.some((d) => d <= depth);
+
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '"') {
+      i = skipDoubleQuotedIdentifier(sql, i);
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      activeSubqueryDepths.splice(
+        0,
+        activeSubqueryDepths.length,
+        ...activeSubqueryDepths.filter((d) => d < depth),
+      );
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+
+    if (depth > 0 && isWordAt(sql, i, "select")) {
+      activeSubqueryDepths.push(depth);
+      i += "select".length - 1;
+      continue;
+    }
+
+    for (const fn of AGGREGATE_FUNCTIONS) {
+      if (!isWordAt(sql, i, fn)) continue;
+      const openIndex = skipSqlSpaces(sql, i + fn.length);
+      if (sql[openIndex] === "(" && !insideSubquery() && !isWindowAggregateCall(sql, openIndex)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Infer whether a SQL query returns a single row or many rows.
+ * Conservative rules: INSERT ... RETURNING → single; UPDATE/DELETE ... RETURNING → many.
+ */
+export function inferSqlCardinality(sqlText) {
+  const sql = stripSqlForInference(sqlText);
+  if (!sql) return null;
+
+  if (hasTopLevelLimitOne(sql) || hasTopLevelFetchOne(sql)) return "single";
+
+  if (/\breturning\b/i.test(sql) && /^insert\b/i.test(sql.trim())) return "single";
+
+  const startsLikeRead = /^(select|with)\b/i.test(sql);
+  if (startsLikeRead && hasTopLevelSetOperation(sql)) return "many";
+
+  const outerSelectList = findOuterSelectList(sql);
+  const hasAggregate = outerSelectList ? hasOuterAggregateFunction(outerSelectList) : false;
+  const hasGroupBy = hasTopLevelGroupBy(sql);
+  if (startsLikeRead && hasAggregate && !hasGroupBy) return "single";
+
+  return "many";
+}
+
+/**
+ * True when SQL clearly proves at most one row (for output_cardinality: single validation).
+ */
+export function sqlProvesSingleRow(sqlText) {
+  return inferSqlCardinality(sqlText) === "single";
+}
+
+/**
+ * Parse node id from a nodes.* placeholder expression (supports bracket index).
+ * e.g. nodes.create_payment[0].id → create_payment
+ */
+export function referencedNodeIdFromNodesExpression(expr) {
+  const trimmed = String(expr || "").trim();
+  const match = /^nodes\.([A-Za-z_][A-Za-z0-9_-]*)/.exec(trimmed);
+  return match?.[1] ?? null;
+}
+
+export function stripePlaceholderIssue(placeholder, nodeId, nodeType) {
+  if (nodeType !== "stripe") return null;
+  const prefix = `nodes.${nodeId}.`;
+  if (!String(placeholder).startsWith(prefix)) return null;
+  const rest = String(placeholder).slice(prefix.length);
+  if (!rest || rest.startsWith("output.")) return null;
+  return {
+    rule: "stripe_output_wrong_path",
+    message: `Placeholder \${${placeholder}} is not the Stripe node output shape. Use output.metadata.*.`,
+    fix_hint: `Use \${nodes.${nodeId}.output.metadata.url} for checkout URL and \${nodes.${nodeId}.output.metadata.id} for session id.`,
+    example_fix: `\${nodes.${nodeId}.output.metadata.url}`,
+  };
+}
+
+export function databaseManyRowPlaceholderIssue(placeholder, nodeId, cardinality) {
+  if (cardinality !== "many") return null;
+  if (/\[\d+\]/.test(placeholder)) return null;
+  const match = /^nodes\.[A-Za-z_][A-Za-z0-9_-]*\.([A-Za-z_][A-Za-z0-9_-]*)/.exec(String(placeholder));
+  if (!match) return null;
+  const prop = match[1];
+  return {
+    rule: "node_output_many_direct_property",
+    message: `Placeholder \${${placeholder}} reads '${prop}' directly from node '${nodeId}', but that node returns many rows.`,
+    fix_hint: `Use \${nodes.${nodeId}[0].${prop}} or process \${nodes.${nodeId}} in javascript_code. For INSERT ... RETURNING (single row), use \${nodes.${nodeId}.${prop}} without [0].`,
+    example_fix: `\${nodes.${nodeId}[0].${prop}}`,
+  };
+}
+
+/** Top-level keys from endpoint output schema (`type: object` + `properties`). */
+export function outputSchemaPropertyNames(outputSchema) {
+  if (!outputSchema || typeof outputSchema !== "object" || Array.isArray(outputSchema)) {
+    return new Set();
+  }
+  const props = outputSchema.properties;
+  if (!props || typeof props !== "object" || Array.isArray(props)) return new Set();
+  return new Set(Object.keys(props));
+}
+
+/** Keys on workflow.output mapping object. */
+export function workflowOutputKeys(workflowOutput) {
+  if (!workflowOutput || typeof workflowOutput !== "object" || Array.isArray(workflowOutput)) {
+    return new Set();
+  }
+  return new Set(Object.keys(workflowOutput));
+}
+
+/** Compare workflow.output keys against declared output.properties (extras = mismatch). */
+export function workflowOutputMismatchKeys(outputSchema, workflowOutput) {
+  const declared = outputSchemaPropertyNames(outputSchema);
+  const mapped = workflowOutputKeys(workflowOutput);
+  if (declared.size === 0 || mapped.size === 0) return [];
+  return [...mapped].filter((key) => !declared.has(key));
+}