@dypai-ai/workflow-core 0.1.0

package/fixtures/capability-catalog.json

@@ -0,0 +1,126 @@
+{
+  "version": "capability-catalog.v1",
+  "engine_version": "test-fixture",
+  "content_hash": "fixture-capability-catalog",
+  "groups": [
+    {
+      "id": "dypai.db",
+      "namespace": "dypai",
+      "resource": "db",
+      "version": 1,
+      "label": "DYPAI Database",
+      "category": "database",
+      "docs": "Declarative and SQL database operations backed by Postgres.",
+      "operations": [
+        {
+          "id": "dypai.db.query",
+          "group_id": "dypai.db",
+          "operation": "query",
+          "name": "Run SQL query",
+          "authoring_signature": "dypai.db.query({ sql, params? })",
+          "input_schema": {
+            "type": "object",
+            "required": ["sql"],
+            "properties": {
+              "sql": { "type": "string" },
+              "params": { "type": "object" }
+            }
+          },
+          "side_effects": ["db.read"],
+          "engine_binding": {
+            "node_type": "dypai_database",
+            "operation": "query",
+            "adapter": "dypai.db"
+          }
+        },
+        {
+          "id": "dypai.db.insert",
+          "group_id": "dypai.db",
+          "operation": "insert",
+          "name": "Insert row",
+          "authoring_signature": "dypai.db.insert({ table, values, returning? })",
+          "input_schema": {
+            "type": "object",
+            "required": ["table", "values"],
+            "properties": {
+              "table": { "type": "string" },
+              "values": { "type": "object" },
+              "returning": { "type": "array", "items": { "type": "string" } }
+            }
+          },
+          "side_effects": ["db.write"],
+          "engine_binding": {
+            "node_type": "dypai_database",
+            "operation": "query",
+            "adapter": "dypai.db"
+          }
+        }
+      ]
+    },
+    {
+      "id": "stripe.checkout",
+      "namespace": "stripe",
+      "resource": "checkout",
+      "version": 1,
+      "label": "Stripe Checkout",
+      "category": "payments",
+      "provider": "Stripe",
+      "operations": [
+        {
+          "id": "stripe.checkout.createSession",
+          "group_id": "stripe.checkout",
+          "operation": "createSession",
+          "name": "Create checkout session",
+          "authoring_signature": "stripe.checkout.createSession({ mode, price_id, success_url, cancel_url, metadata? })",
+          "input_schema": {
+            "type": "object",
+            "required": ["mode", "price_id", "success_url", "cancel_url"],
+            "properties": {
+              "mode": { "type": "string" },
+              "price_id": { "type": "string" },
+              "success_url": { "type": "string" },
+              "cancel_url": { "type": "string" },
+              "metadata": { "type": "object" }
+            }
+          },
+          "required_credentials": ["stripe"],
+          "engine_binding": {
+            "node_type": "stripe",
+            "operation": "stripe_create_checkout_session"
+          }
+        }
+      ]
+    },
+    {
+      "id": "google.sheets",
+      "namespace": "google",
+      "resource": "sheets",
+      "version": 1,
+      "label": "Google Sheets",
+      "category": "data",
+      "operations": [
+        {
+          "id": "google.sheets.readRows",
+          "group_id": "google.sheets",
+          "operation": "readRows",
+          "name": "Read rows",
+          "authoring_signature": "google.sheets.readRows({ spreadsheet_id, sheet_name?, range? })",
+          "input_schema": {
+            "type": "object",
+            "required": ["spreadsheet_id"],
+            "properties": {
+              "spreadsheet_id": { "type": "string" },
+              "sheet_name": { "type": "string" },
+              "range": { "type": "string" }
+            }
+          },
+          "required_credentials": ["google_sheets"],
+          "engine_binding": {
+            "node_type": "google_sheets",
+            "operation": "read_rows"
+          }
+        }
+      ]
+    }
+  ]
+}

package/fixtures/legacy-create-booking.yaml

@@ -0,0 +1,40 @@
+name: create-booking
+method: POST
+trigger:
+  http_api:
+    auth_mode: public
+input:
+  type: object
+  required: [name, email, date]
+  additionalProperties: false
+  properties:
+    name:
+      type: string
+    email:
+      type: string
+      format: email
+    date:
+      type: string
+      format: date
+output:
+  type: object
+  additionalProperties: false
+  properties:
+    id:
+      type: string
+    name:
+      type: string
+    email:
+      type: string
+    date:
+      type: string
+response_cardinality: single
+workflow:
+  nodes:
+    - id: booking
+      type: dypai_database
+      operation: query
+      query: |
+        INSERT INTO public.bookings (name, email, date)
+        VALUES (${input.name}, ${input.email}, ${input.date})
+        RETURNING id, name, email, date

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dypai-ai/workflow-core",
+  "version": "0.1.0",
+  "description": "Workflow IR, adapters, and validation for DYPAI Flow endpoint authoring",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DYPAI-SOLUTIONS/dypai.git"
+  },
+  "homepage": "https://dypai.ai",
+  "keywords": [
+    "dypai",
+    "workflow",
+    "flow",
+    "ir"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "fixtures/",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "typescript": "^5.7.2"
+  }
+}

package/src/adapters/adapters.test.ts

@@ -0,0 +1,168 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "bun:test";
+import { flowDefinitionToIr } from "./flowDefinitionToIr";
+import { irToWorkflowCodeV2, stableStringifyWorkflowCode } from "./irToWorkflowCodeV2";
+import { legacyYamlToIr } from "./legacyYamlToIr";
+import { placeholderToRef } from "./placeholderToRef";
+import { createBookingFlowDefinition } from "../fixtures/createBooking.flow";
+import { createBookingWorkflowIR } from "../fixtures/createBooking.ir";
+import { listBookingsWorkflowIR } from "../fixtures/listBookings.ir";
+import { validateWorkflowIR } from "../ir/validate";
+
+const fixturesDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "fixtures");
+
+describe("legacyYamlToIr", () => {
+  test("imports simple CRUD YAML into WorkflowIR with YAML source maps", () => {
+    const yamlText = readFileSync(join(fixturesDir, "legacy-create-booking.yaml"), "utf-8");
+    const imported = legacyYamlToIr(yamlText, { file: "dypai/endpoints/create-booking.yaml" });
+
+    expect(imported.ok).toBe(true);
+    expect(imported.value?.name).toBe("create-booking");
+    expect(imported.value?.source?.kind).toBe("legacy-yaml");
+    expect(imported.value?.steps.some((step) => step.node === "dypai.db" && step.operation === "query")).toBe(true);
+
+    const validated = validateWorkflowIR(imported.value);
+    expect(validated.ok).toBe(true);
+  });
+
+  test("flags mutation+query anti-pattern during import", () => {
+    const yamlText = `
+name: bad-create
+method: POST
+trigger:
+  http_api:
+    auth_mode: public
+input:
+  type: object
+  properties: {}
+output:
+  type: object
+  properties:
+    id:
+      type: string
+workflow:
+  nodes:
+    - id: create
+      type: dypai_database
+      operation: mutation
+      query: INSERT INTO public.items (name) VALUES (\${input.name}) RETURNING id
+`;
+    const imported = legacyYamlToIr(yamlText, { file: "dypai/endpoints/bad-create.yaml" });
+    expect(imported.ok).toBe(false);
+    expect(imported.diagnostics.some((item) => item.rule === "legacy_mutation_with_query")).toBe(true);
+  });
+});
+
+describe("flowDefinitionToIr", () => {
+  test("compiles FlowDefinition fixture to valid WorkflowIR", () => {
+    const workflow = flowDefinitionToIr(createBookingFlowDefinition);
+    const validated = validateWorkflowIR(workflow);
+    expect(validated.ok).toBe(true);
+    expect(workflow.steps.some((step) => step.node === "dypai.db" && step.operation === "insert")).toBe(true);
+    expect(workflow.responseMap.booking.kind).toBe("step");
+  });
+});
+
+describe("irToWorkflowCodeV2", () => {
+  test("adapts create-booking IR without invalid engine patterns", () => {
+    const adapted = irToWorkflowCodeV2(createBookingWorkflowIR);
+    expect(adapted.ok).toBe(true);
+    expect(adapted.value?.schema_version).toBe("2.0");
+
+    const databaseNode = adapted.value?.nodes.find((node) => node.id === "booking");
+    expect(databaseNode?.node_type).toBe("dypai_database");
+    expect(databaseNode?.parameters.operation).toBe("query");
+    expect(databaseNode?.parameters.query).toContain("INSERT INTO public.bookings");
+    expect(databaseNode?.parameters.operation).not.toBe("mutation");
+
+    const composeNode = adapted.value?.nodes.find((node) => node.is_return);
+    expect(composeNode?.node_type).toBe("set_fields");
+    expect(composeNode?.parameters.operation).toBe("compose");
+    expect(composeNode?.parameters.fields).toEqual({
+      booking: "${vars.booking.row}",
+    });
+    expect(adapted.value?.edges.some((edge) => edge.target === "respond")).toBe(false);
+    expect(adapted.value?.edges).toEqual([
+      { source: "booking", target: "__response" },
+    ]);
+  });
+
+  test("adapts list-bookings IR with jwt trigger metadata", () => {
+    expect(validateWorkflowIR(listBookingsWorkflowIR).ok).toBe(true);
+    const adapted = irToWorkflowCodeV2(listBookingsWorkflowIR);
+    expect(adapted.ok).toBe(true);
+    expect(adapted.value?.metadata?.response_cardinality).toBe("many");
+    expect(adapted.value?.execution_config.triggers.http_api).toMatchObject({
+      enabled: true,
+      auth_mode: "jwt",
+    });
+
+    const listNode = adapted.value?.nodes.find((node) => node.id === "bookings");
+    expect(String(listNode?.parameters.query)).toContain("SELECT * FROM public.bookings");
+    expect(String(listNode?.parameters.query)).toContain("${current_user_id}");
+    expect(String(listNode?.parameters.query)).toContain("LIMIT ${input.limit}");
+    expect(String(listNode?.parameters.query)).toContain("OFFSET ${input.offset}");
+  });
+
+  test("generates deterministic workflow_code for golden comparison", () => {
+    const first = stableStringifyWorkflowCode(irToWorkflowCodeV2(createBookingWorkflowIR).value!);
+    const second = stableStringifyWorkflowCode(irToWorkflowCodeV2(createBookingWorkflowIR).value!);
+    expect(first).toBe(second);
+    expect(first).toContain('"schema_version": "2.0"');
+    expect(first).not.toContain("operation\": \"mutation\"");
+  });
+
+  test("round-trips legacy YAML -> IR -> workflow_code for create-booking", () => {
+    const yamlText = readFileSync(join(fixturesDir, "legacy-create-booking.yaml"), "utf-8");
+    const imported = legacyYamlToIr(yamlText, { file: "dypai/endpoints/create-booking.yaml" });
+    expect(imported.ok).toBe(true);
+
+    const validated = validateWorkflowIR(imported.value);
+    expect(validated.ok).toBe(true);
+
+    const adapted = irToWorkflowCodeV2(imported.value!);
+    expect(adapted.ok).toBe(true);
+    expect(adapted.value?.nodes.some((node) => node.node_type === "dypai_database")).toBe(true);
+    expect(adapted.value?.nodes.some((node) => node.node_type === "set_fields" && node.is_return)).toBe(true);
+  });
+});
+
+describe("legacy compatibility helpers", () => {
+  test("parses indexed vars placeholders into step refs", () => {
+    expect(placeholderToRef("${vars.count[0].total}")).toEqual({
+      kind: "step",
+      stepId: "count",
+      path: ["0", "total"],
+    });
+  });
+
+  test("imports unsupported legacy nodes as valid legacy.workflow steps", () => {
+    const yamlText = `
+name: proxy
+method: POST
+trigger:
+  http_api:
+    auth_mode: public
+input:
+  type: object
+  properties: {}
+output:
+  type: object
+  properties:
+    ok:
+      type: boolean
+workflow:
+  nodes:
+    - id: call_api
+      type: http_request
+      method: GET
+      url: https://example.com
+`;
+    const imported = legacyYamlToIr(yamlText, { file: "dypai/endpoints/proxy.yaml" });
+    expect(imported.ok).toBe(true);
+    expect(imported.value?.steps.some((step) => step.node === "legacy.workflow")).toBe(true);
+    expect(validateWorkflowIR(imported.value).ok).toBe(true);
+  });
+});

package/src/adapters/engineBinding.ts

@@ -0,0 +1,35 @@
+import type { EngineBindingJson } from "../capabilities/types";
+import { serializeConfig } from "./refToLegacyPlaceholder";
+
+export function applyParameterMap(
+  config: Record<string, unknown>,
+  binding: EngineBindingJson,
+): Record<string, unknown> {
+  if (!binding.parameter_map) {
+    return config;
+  }
+
+  const mapped: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(config)) {
+    mapped[binding.parameter_map[key] ?? key] = value;
+  }
+  return mapped;
+}
+
+export function buildEngineParameters(
+  config: Record<string, unknown>,
+  binding: EngineBindingJson,
+): Record<string, unknown> {
+  const mapped = applyParameterMap(config, binding);
+  const parameters = serializeConfig(mapped);
+
+  if (binding.operation) {
+    parameters.operation = binding.operation;
+  }
+
+  if (binding.static_parameters) {
+    Object.assign(parameters, binding.static_parameters);
+  }
+
+  return parameters;
+}

package/src/adapters/flowDefinitionToIr.ts

@@ -0,0 +1,141 @@
+import type { CapabilityCatalog } from "../capabilities/types";
+import { CapabilityRegistry, resolveCapabilityCall as resolveCatalogCall } from "../capabilities/capabilityRegistry";
+import type {
+  AuthIR,
+  JsonSchema,
+  RefIR,
+  ResponseIR,
+  SourceLocation,
+  TriggerIR,
+  WorkflowIR,
+  WorkflowStepIR,
+} from "../ir/types";
+import { WORKFLOW_IR_VERSION } from "../ir/types";
+
+export type FlowCompileContext = {
+  capabilityCatalog?: CapabilityCatalog;
+};
+
+export type FlowStepDefinition = {
+  id: string;
+  call: string;
+  config: Record<string, unknown>;
+  source?: SourceLocation;
+};
+
+export type FlowDefinition = {
+  name: string;
+  source?: {
+    kind: "flow-ts";
+    file: string;
+  };
+  endpoint?: {
+    description?: string;
+    isTool?: boolean;
+    toolDescription?: string;
+  };
+  trigger: TriggerIR;
+  auth: AuthIR;
+  input: JsonSchema;
+  output: JsonSchema;
+  response?: ResponseIR;
+  steps: FlowStepDefinition[];
+  returns: Record<string, RefIR>;
+  edges?: Array<{ from: string; to: string }>;
+};
+
+const LEGACY_FLOW_ALIASES: Record<string, { node: string; operation: string; version: number }> = {
+  "db.query": { node: "dypai.db", operation: "query", version: 1 },
+  "db.insert": { node: "dypai.db", operation: "insert", version: 1 },
+  "db.update": { node: "dypai.db", operation: "update", version: 1 },
+  "db.list": { node: "dypai.db", operation: "list", version: 1 },
+  "email.send": { node: "dypai.email", operation: "send", version: 1 },
+  "flow.return": { node: "dypai.flow", operation: "return", version: 1 },
+};
+
+const BUILTIN_AUTHORING_GROUPS = new Set(["dypai.db", "dypai.email"]);
+
+export function resolveFlowAlias(
+  call: string,
+  context: FlowCompileContext = {},
+): { node: string; operation: string; version: number } | null {
+  const trimmed = call.trim();
+  if (LEGACY_FLOW_ALIASES[trimmed]) return LEGACY_FLOW_ALIASES[trimmed];
+
+  const registry = context.capabilityCatalog
+    ? CapabilityRegistry.fromCatalog(context.capabilityCatalog)
+    : new CapabilityRegistry();
+
+  const resolved = resolveCatalogCall(trimmed, registry);
+  if (resolved) return resolved;
+
+  const parts = trimmed.split(".");
+  for (let splitAt = parts.length - 1; splitAt >= 2; splitAt -= 1) {
+    const groupId = parts.slice(0, splitAt).join(".");
+    if (!BUILTIN_AUTHORING_GROUPS.has(groupId)) continue;
+    const operation = parts.slice(splitAt).join(".");
+    return { node: groupId, operation, version: 1 };
+  }
+
+  return null;
+}
+
+export function flowDefinitionToIr(
+  definition: FlowDefinition,
+  context: FlowCompileContext = {},
+): WorkflowIR {
+  const steps: WorkflowStepIR[] = definition.steps.map((step) => {
+    const resolved = resolveFlowAlias(step.call, context);
+    if (!resolved) {
+      return {
+        id: step.id,
+        node: "legacy.workflow",
+        operation: "node",
+        version: 1,
+        config: {
+          legacyNode: {
+            id: step.id,
+            type: step.call,
+            ...step.config,
+          },
+        },
+        source: step.source,
+      };
+    }
+
+    return {
+      id: step.id,
+      node: resolved.node,
+      operation: resolved.operation,
+      version: resolved.version,
+      config: step.config,
+      source: step.source,
+      ...(resolved.node === "dypai.flow" && resolved.operation === "return" ? { return: true } : {}),
+    };
+  });
+
+  if (!steps.some((step) => step.node === "dypai.flow" && step.operation === "return")) {
+    steps.push({
+      id: "return",
+      node: "dypai.flow",
+      operation: "return",
+      version: 1,
+      config: {},
+      return: true,
+    });
+  }
+
+  return {
+    version: WORKFLOW_IR_VERSION,
+    name: definition.name,
+    source: definition.source,
+    trigger: definition.trigger,
+    auth: definition.auth,
+    inputSchema: definition.input,
+    outputSchema: definition.output,
+    response: definition.response || { cardinality: "single" },
+    steps,
+    edges: definition.edges,
+    responseMap: definition.returns,
+  };
+}