@contractspec/integration.workflow-devkit 0.1.1

package/dist/node/compiler.js

@@ -0,0 +1,177 @@
+// src/helpers.ts
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+function inferWorkflowDevkitBehavior(step) {
+  return step.runtime?.workflowDevkit?.behavior ?? step.type;
+}
+function resolveWorkflowDevkitEntryStepId(spec) {
+  const entryStepId = spec.definition.entryStepId ?? spec.definition.steps[0]?.id;
+  if (!entryStepId) {
+    throw new Error(`Workflow ${spec.meta.key}.v${spec.meta.version} does not define an entry step.`);
+  }
+  return entryStepId;
+}
+function resolveWorkflowDevkitRunIdentity(spec, runIdentity) {
+  if (runIdentity) {
+    return runIdentity;
+  }
+  const strategy = spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version";
+  const prefix = spec.runtime?.workflowDevkit?.runIdentity?.prefix;
+  const baseIdentity = strategy === "meta-key-version" ? `${spec.meta.key}.v${spec.meta.version}` : `${spec.meta.key}.v${spec.meta.version}`;
+  return prefix ? `${prefix}:${baseIdentity}` : baseIdentity;
+}
+function resolveWorkflowDevkitWaitToken(spec, step, runIdentity) {
+  const runtime = step.runtime?.workflowDevkit;
+  if (!runtime) {
+    return;
+  }
+  const explicitToken = runtime.hookWait?.token ?? runtime.webhookWait?.token ?? runtime.approvalWait?.token ?? runtime.streamSession?.followUpToken;
+  if (explicitToken) {
+    return explicitToken;
+  }
+  const tokenStrategy = spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic";
+  const prefix = spec.runtime?.workflowDevkit?.hookTokens?.prefix ?? spec.meta.key;
+  const stableStepId = sanitizeIdentifier(step.id);
+  if (tokenStrategy === "session-scoped") {
+    const resolvedRunIdentity = sanitizeIdentifier(resolveWorkflowDevkitRunIdentity(spec, runIdentity));
+    return `${prefix}:${resolvedRunIdentity}:${stableStepId}`;
+  }
+  if (tokenStrategy === "step-scoped") {
+    return `${prefix}:v${spec.meta.version}:${stableStepId}`;
+  }
+  return `${prefix}:${stableStepId}`;
+}
+function resolveWorkflowDevkitNextStepId(spec, step, data, input, output) {
+  const transitions = spec.definition.transitions.filter((transition) => transition.from === step.id);
+  for (const transition of transitions) {
+    if (evaluateExpression(transition.condition, {
+      data,
+      input,
+      output
+    })) {
+      return transition.to;
+    }
+  }
+  return null;
+}
+function mergeWorkflowDevkitData(current, input, output) {
+  const next = { ...current };
+  if (isRecord(input)) {
+    Object.assign(next, input);
+  }
+  if (isRecord(output)) {
+    Object.assign(next, output);
+  }
+  return next;
+}
+function sanitizeIdentifier(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/compiler.ts
+function compileWorkflowSpecToWorkflowDevkit(spec) {
+  return {
+    entryStepId: resolveWorkflowDevkitEntryStepId(spec),
+    hostTarget: spec.runtime?.workflowDevkit?.hostTarget ?? "generic",
+    hookTokenStrategy: spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic",
+    integrationMode: spec.runtime?.workflowDevkit?.integrationMode ?? "manual",
+    runIdentityStrategy: spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version",
+    specKey: spec.meta.key,
+    specVersion: spec.meta.version,
+    steps: spec.definition.steps.map((step) => ({
+      behavior: inferWorkflowDevkitBehavior(step),
+      id: step.id,
+      label: step.label,
+      operationRef: step.action?.operation ? `${step.action.operation.key}.v${step.action.operation.version}` : undefined,
+      runtime: step.runtime?.workflowDevkit,
+      transitions: spec.definition.transitions.filter((transition) => transition.from === step.id).map((transition) => ({
+        condition: transition.condition,
+        to: transition.to
+      })),
+      type: step.type,
+      waitToken: resolveWorkflowDevkitWaitToken(spec, step)
+    }))
+  };
+}
+function generateWorkflowDevkitArtifacts(spec, options) {
+  const compilation = compileWorkflowSpecToWorkflowDevkit(spec);
+  const workflowFunctionName = options.workflowFunctionName ?? `${sanitizeIdentifier(options.exportName)}WorkflowDevkit`;
+  return {
+    genericBootstrap: createGenericBootstrapTemplate(options.exportName, workflowFunctionName),
+    manifest: JSON.stringify(compilation, null, 2),
+    nextFollowUpRoute: createFollowUpRouteTemplate(workflowFunctionName),
+    nextStartRoute: createStartRouteTemplate(workflowFunctionName),
+    nextStreamRoute: createStreamRouteTemplate(),
+    workflowModule: createWorkflowModuleTemplate(options.exportName, options.specImportPath, workflowFunctionName)
+  };
+}
+function createGenericBootstrapTemplate(exportName, workflowFunctionName) {
+  return `import { ${workflowFunctionName} } from "./${sanitizeIdentifier(exportName)}.workflow-devkit";
+
+export const ${sanitizeIdentifier(exportName)}WorkflowDevkitBootstrap = {
+  workflow: ${workflowFunctionName},
+  createBridge() {
+    return {
+      executeAutomationStep: async () => {
+        throw new Error("Provide executeAutomationStep in your generic host bridge.");
+      },
+    };
+  },
+};
+`;
+}
+function createStartRouteTemplate(workflowFunctionName) {
+  return `import { createWorkflowDevkitStartRoute } from "@contractspec/integration.workflow-devkit";
+import { ${workflowFunctionName} } from "./workflow";
+
+export const POST = createWorkflowDevkitStartRoute({
+  workflow: ${workflowFunctionName},
+  async buildArgs(body) {
+    return [body];
+  },
+});
+`;
+}
+function createFollowUpRouteTemplate(workflowFunctionName) {
+  return `import { createWorkflowDevkitFollowUpRoute } from "@contractspec/integration.workflow-devkit";
+
+export const POST = createWorkflowDevkitFollowUpRoute({
+  resolveToken({ runId }) {
+    return \`${workflowFunctionName}:\${runId}\`;
+  },
+});
+`;
+}
+function createStreamRouteTemplate() {
+  return `import { createWorkflowDevkitStreamRoute } from "@contractspec/integration.workflow-devkit";
+
+export const GET = createWorkflowDevkitStreamRoute();
+`;
+}
+function createWorkflowModuleTemplate(exportName, specImportPath, workflowFunctionName) {
+  return `import { createHook, createWebhook, sleep } from "workflow";
+import { runWorkflowSpecWithWorkflowDevkit } from "@contractspec/integration.workflow-devkit";
+import { ${exportName} } from "${specImportPath}";
+
+export async function ${workflowFunctionName}(input = {}, bridge = {}) {
+  "use workflow";
+
+  return runWorkflowSpecWithWorkflowDevkit({
+    spec: ${exportName},
+    initialData: input,
+    bridge,
+    primitives: {
+      sleep,
+      createHook,
+      createWebhook,
+    },
+  });
+}
+`;
+}
+export {
+  generateWorkflowDevkitArtifacts,
+  compileWorkflowSpecToWorkflowDevkit
+};

package/dist/node/helpers.js

@@ -0,0 +1,80 @@
+// src/helpers.ts
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+function inferWorkflowDevkitBehavior(step) {
+  return step.runtime?.workflowDevkit?.behavior ?? step.type;
+}
+function resolveWorkflowDevkitEntryStepId(spec) {
+  const entryStepId = spec.definition.entryStepId ?? spec.definition.steps[0]?.id;
+  if (!entryStepId) {
+    throw new Error(`Workflow ${spec.meta.key}.v${spec.meta.version} does not define an entry step.`);
+  }
+  return entryStepId;
+}
+function resolveWorkflowDevkitRunIdentity(spec, runIdentity) {
+  if (runIdentity) {
+    return runIdentity;
+  }
+  const strategy = spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version";
+  const prefix = spec.runtime?.workflowDevkit?.runIdentity?.prefix;
+  const baseIdentity = strategy === "meta-key-version" ? `${spec.meta.key}.v${spec.meta.version}` : `${spec.meta.key}.v${spec.meta.version}`;
+  return prefix ? `${prefix}:${baseIdentity}` : baseIdentity;
+}
+function resolveWorkflowDevkitWaitToken(spec, step, runIdentity) {
+  const runtime = step.runtime?.workflowDevkit;
+  if (!runtime) {
+    return;
+  }
+  const explicitToken = runtime.hookWait?.token ?? runtime.webhookWait?.token ?? runtime.approvalWait?.token ?? runtime.streamSession?.followUpToken;
+  if (explicitToken) {
+    return explicitToken;
+  }
+  const tokenStrategy = spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic";
+  const prefix = spec.runtime?.workflowDevkit?.hookTokens?.prefix ?? spec.meta.key;
+  const stableStepId = sanitizeIdentifier(step.id);
+  if (tokenStrategy === "session-scoped") {
+    const resolvedRunIdentity = sanitizeIdentifier(resolveWorkflowDevkitRunIdentity(spec, runIdentity));
+    return `${prefix}:${resolvedRunIdentity}:${stableStepId}`;
+  }
+  if (tokenStrategy === "step-scoped") {
+    return `${prefix}:v${spec.meta.version}:${stableStepId}`;
+  }
+  return `${prefix}:${stableStepId}`;
+}
+function resolveWorkflowDevkitNextStepId(spec, step, data, input, output) {
+  const transitions = spec.definition.transitions.filter((transition) => transition.from === step.id);
+  for (const transition of transitions) {
+    if (evaluateExpression(transition.condition, {
+      data,
+      input,
+      output
+    })) {
+      return transition.to;
+    }
+  }
+  return null;
+}
+function mergeWorkflowDevkitData(current, input, output) {
+  const next = { ...current };
+  if (isRecord(input)) {
+    Object.assign(next, input);
+  }
+  if (isRecord(output)) {
+    Object.assign(next, output);
+  }
+  return next;
+}
+function sanitizeIdentifier(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+export {
+  sanitizeIdentifier,
+  resolveWorkflowDevkitWaitToken,
+  resolveWorkflowDevkitRunIdentity,
+  resolveWorkflowDevkitNextStepId,
+  resolveWorkflowDevkitEntryStepId,
+  mergeWorkflowDevkitData,
+  inferWorkflowDevkitBehavior
+};