@bpmnkit/core 0.1.1 → 0.1.2

package/dist/plan/merge.js

@@ -0,0 +1,80 @@
+/**
+ * Applies a `ProcessPlan` delta onto an already-compiled `BpmnDefinitions`
+ * process — an id-based structural merge, not a byte-stable patch: elements
+ * whose id already exists are replaced, new elements are appended, and
+ * auto-layout re-runs over the whole diagram (so untouched elements keep
+ * their meaning but not necessarily their exact DI coordinates).
+ */
+import { applyAutoLayout } from "../bpmn/auto-layout.js";
+import { Bpmn } from "../bpmn/index.js";
+import { optimize } from "../bpmn/optimize/index.js";
+import { compilePlan } from "./compile.js";
+/**
+ * Compiles `delta` standalone, then merges its elements/flows into
+ * `existing`'s matching process by id (matching ids are replaced, new ids
+ * are appended). `delta.steps[0]` must still be a `start` step — the merge
+ * only uses `delta`'s flow elements and sequence flows, and drops the
+ * delta's own start/end events when a same-id start/end already exists in
+ * `existing`.
+ */
+export function mergePlan(existing, delta, opts = {}) {
+    const deltaResult = compilePlan(delta, { ...opts, skipAutoFix: true });
+    if (!deltaResult.defs)
+        return deltaResult;
+    const targetProcess = existing.processes.find((p) => p.id === delta.process.id) ?? existing.processes[0];
+    const deltaProcess = deltaResult.defs.processes[0];
+    if (!targetProcess || !deltaProcess) {
+        return { problems: [{ path: "process", message: "Could not resolve a process to merge into" }] };
+    }
+    const problems = [];
+    for (const el of deltaProcess.flowElements) {
+        const existingIndex = targetProcess.flowElements.findIndex((e) => e.id === el.id);
+        if (existingIndex >= 0)
+            targetProcess.flowElements[existingIndex] = el;
+        else
+            targetProcess.flowElements.push(el);
+    }
+    // Sequence-flow ids aren't stable across compiles, so merging by flow id
+    // would leave stale flows around any element the delta re-wires. Instead:
+    // drop every existing flow touching an element the delta redefines, then
+    // add the delta's flows fresh. Flows between two untouched elements are
+    // left alone.
+    const deltaElementIds = new Set(deltaProcess.flowElements.map((e) => e.id));
+    targetProcess.sequenceFlows = targetProcess.sequenceFlows.filter((f) => !deltaElementIds.has(f.sourceRef) && !deltaElementIds.has(f.targetRef));
+    targetProcess.sequenceFlows.push(...deltaProcess.sequenceFlows);
+    // Pull in any new root error/message/signal/escalation definitions the delta introduced.
+    for (const err of deltaResult.defs.errors) {
+        if (!existing.errors.some((e) => e.id === err.id))
+            existing.errors.push(err);
+    }
+    for (const msg of deltaResult.defs.messages) {
+        if (!existing.messages.some((m) => m.id === msg.id))
+            existing.messages.push(msg);
+    }
+    for (const sig of deltaResult.defs.signals) {
+        if (!existing.signals.some((s) => s.id === sig.id))
+            existing.signals.push(sig);
+    }
+    for (const esc of deltaResult.defs.escalations) {
+        if (!existing.escalations.some((e) => e.id === esc.id))
+            existing.escalations.push(esc);
+    }
+    let laidOut = applyAutoLayout(existing);
+    if (!opts.skipAutoFix) {
+        const report = optimize(laidOut);
+        for (const finding of report.findings)
+            finding.applyFix?.(laidOut);
+        laidOut = applyAutoLayout(laidOut);
+    }
+    const finalReport = optimize(laidOut);
+    for (const finding of finalReport.findings) {
+        if (finding.severity === "error") {
+            problems.push({
+                path: finding.elementIds.length > 0 ? `element:${finding.elementIds.join(",")}` : "process",
+                message: finding.message,
+            });
+        }
+    }
+    return { defs: laidOut, xml: Bpmn.export(laidOut), problems };
+}
+//# sourceMappingURL=merge.js.map

package/dist/plan/slug.d.ts

@@ -0,0 +1,5 @@
+/** Derives a stable, readable element id from a step name, deduping against ids already used in this plan. */
+export declare function slugify(text: string): string;
+/** Returns a unique id: `base`, or `base_2`, `base_3`, … if `base` is already taken. */
+export declare function uniqueId(base: string, taken: Set<string>): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/plan/slug.js

@@ -0,0 +1,22 @@
+/** Derives a stable, readable element id from a step name, deduping against ids already used in this plan. */
+export function slugify(text) {
+    const slug = text
+        .trim()
+        .replace(/[^a-zA-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return slug.length > 0 ? slug : "element";
+}
+/** Returns a unique id: `base`, or `base_2`, `base_3`, … if `base` is already taken. */
+export function uniqueId(base, taken) {
+    if (!taken.has(base)) {
+        taken.add(base);
+        return base;
+    }
+    let n = 2;
+    while (taken.has(`${base}_${n}`))
+        n++;
+    const id = `${base}_${n}`;
+    taken.add(id);
+    return id;
+}
+//# sourceMappingURL=slug.js.map

package/dist/plan/types.d.ts

@@ -0,0 +1,225 @@
+/**
+ * ProcessPlan — the typed intermediate representation Claude (or any LLM)
+ * authors instead of BPMN XML. `compilePlan()` turns a plan into valid,
+ * laid-out, executable BPMN via the `@bpmnkit/core` builder; the model never
+ * touches XML, DI, element IDs, or connector property keys directly.
+ *
+ * Every string field documented as FEEL follows this SDK's existing
+ * convention throughout: a leading "=" makes it a FEEL expression, its
+ * absence makes it a literal string. This matches how `zeebe:input`/`output`
+ * `source` values already work in `@bpmnkit/core`.
+ */
+/** A connector reference — resolved against `@bpmnkit/connectors` (or an equivalent resolver) at compile time. */
+export interface PlanConnectorRef {
+    /** Bundled template id, e.g. "io.camunda.connectors.Slack.v1". */
+    template: string;
+    /** Values keyed by the template's input keys — see `ConnectorSummary.requiredInputs`/`optionalInputs`. */
+    values?: Record<string, string>;
+}
+/** An error boundary attached to a step that can throw a BPMN error. */
+export interface PlanErrorBoundary {
+    /**
+     * BPMN error code this boundary catches. Required: the underlying builder
+     * only emits an `errorEventDefinition` when a code is given, so an
+     * omitted `errorCode` produces an untyped (non-functional) boundary event.
+     */
+    errorCode: string;
+    /** Steps to run when the error is caught. */
+    steps: PlanStep[];
+    /** False = non-interrupting boundary event (default true). */
+    interrupting?: boolean;
+}
+/** A timer boundary attached to a step. */
+export interface PlanTimerBoundary {
+    duration?: string;
+    date?: string;
+    cycle?: string;
+    steps: PlanStep[];
+    interrupting?: boolean;
+}
+interface PlanStepBase {
+    /** Stable element id. Auto-derived from `name` (slugified, deduped) if omitted. */
+    id?: string;
+    name?: string;
+    /** Shown as documentation on the element; becomes the AI Agent tool description for tools inside an `aiAgent` step. */
+    documentation?: string;
+    errorBoundary?: PlanErrorBoundary;
+    timerBoundary?: PlanTimerBoundary;
+}
+export interface PlanStartStep extends PlanStepBase {
+    kind: "start";
+    timer?: {
+        duration?: string;
+        date?: string;
+        cycle?: string;
+    };
+    message?: {
+        name: string;
+    };
+    /** Inbound connector template (e.g. a webhook start event). */
+    connector?: PlanConnectorRef;
+}
+export interface PlanConnectorStep extends PlanStepBase {
+    kind: "connector";
+    connector: PlanConnectorRef;
+    retries?: string;
+}
+export interface PlanServiceTaskStep extends PlanStepBase {
+    kind: "serviceTask";
+    jobType: string;
+    inputs?: Record<string, string>;
+    outputs?: Record<string, string>;
+    taskHeaders?: Record<string, string>;
+    retries?: string;
+}
+export interface PlanUserTaskStep extends PlanStepBase {
+    kind: "userTask";
+    formId?: string;
+    assignee?: string;
+    candidateGroups?: string;
+    candidateUsers?: string;
+    dueDate?: string;
+    followUpDate?: string;
+    priority?: number;
+}
+export interface PlanBusinessRuleTaskStep extends PlanStepBase {
+    kind: "businessRuleTask";
+    decisionId: string;
+    resultVariable?: string;
+}
+export interface PlanScriptTaskStep extends PlanStepBase {
+    kind: "scriptTask";
+    expression: string;
+    resultVariable: string;
+}
+export interface PlanSendTaskStep extends PlanStepBase {
+    kind: "sendTask";
+    messageName: string;
+}
+export interface PlanReceiveTaskStep extends PlanStepBase {
+    kind: "receiveTask";
+    messageName: string;
+    correlationKey?: string;
+}
+export interface PlanCallActivityStep extends PlanStepBase {
+    kind: "callActivity";
+    processId: string;
+    propagateAllChildVariables?: boolean;
+}
+/** One tool available to an `aiAgent` step. */
+export interface PlanAgentTool {
+    id: string;
+    description: string;
+    /** A connector-backed tool. */
+    connector?: PlanConnectorRef;
+    /** A plain job-worker tool (mutually exclusive with `connector`). */
+    jobType?: string;
+    params?: Array<{
+        name: string;
+        description: string;
+        type?: "string" | "number" | "boolean" | "integer" | "array" | "object";
+        required?: boolean;
+        schema?: Record<string, unknown>;
+        /** Input-mapping target on the tool activity (default: same as `name`). */
+        target?: string;
+    }>;
+    resultExpression?: string;
+}
+export interface PlanAiAgentStep extends PlanStepBase {
+    kind: "aiAgent";
+    provider: string;
+    model: string;
+    /** Extra dotted zeebe:input bindings — auth, endpoint, region, etc. Keys match the bundled template's input keys. */
+    providerInputs?: Record<string, string>;
+    systemPrompt: string;
+    userPrompt: string;
+    memoryStorageType?: string;
+    maxModelCalls?: number;
+    outputVariable?: string;
+    tools: PlanAgentTool[];
+    completionCondition?: string;
+    cancelRemainingInstances?: boolean;
+    retries?: string;
+}
+export interface PlanBranch {
+    name?: string;
+    /** FEEL condition (required unless `default` is set). */
+    condition?: string;
+    default?: boolean;
+    steps: PlanStep[];
+}
+export interface PlanGatewayStep extends PlanStepBase {
+    kind: "gateway";
+    gatewayType: "exclusive" | "parallel" | "inclusive" | "eventBased";
+    branches: PlanBranch[];
+}
+export interface PlanSubProcessStep extends PlanStepBase {
+    kind: "subProcess";
+    steps: PlanStep[];
+    multiInstance?: {
+        isSequential?: boolean;
+        collection: string;
+        elementVariable?: string;
+        completionCondition?: string;
+    };
+}
+export interface PlanWaitStep extends PlanStepBase {
+    kind: "wait";
+    timer?: {
+        duration?: string;
+        date?: string;
+        cycle?: string;
+    };
+    message?: {
+        name: string;
+        correlationKey: string;
+    };
+}
+export interface PlanEndStep extends PlanStepBase {
+    kind: "end";
+    errorCode?: string;
+    terminate?: boolean;
+}
+/** Escape hatch for anything the plan format can't express yet — a raw builder-options object, applied as-is. */
+export interface PlanRawStep extends PlanStepBase {
+    kind: "raw";
+    elementType: string;
+    options?: Record<string, unknown>;
+}
+export type PlanStep = PlanStartStep | PlanConnectorStep | PlanServiceTaskStep | PlanUserTaskStep | PlanBusinessRuleTaskStep | PlanScriptTaskStep | PlanSendTaskStep | PlanReceiveTaskStep | PlanCallActivityStep | PlanAiAgentStep | PlanGatewayStep | PlanSubProcessStep | PlanWaitStep | PlanEndStep | PlanRawStep;
+export interface PlanInputVariable {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+export interface PlanScenario {
+    name: string;
+    inputs?: Record<string, unknown>;
+    /** jobType → { outputs } or { error: { code, message? } } */
+    mocks?: Record<string, {
+        outputs?: Record<string, unknown>;
+    } | {
+        error: {
+            code: string;
+            message?: string;
+        };
+    }>;
+    expect?: {
+        path?: string[];
+        variables?: Record<string, unknown>;
+    };
+}
+export interface ProcessPlan {
+    version: 1;
+    process: {
+        id: string;
+        name?: string;
+        versionTag?: string;
+    };
+    inputs?: PlanInputVariable[];
+    steps: PlanStep[];
+    tests?: PlanScenario[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/plan/types.js

@@ -0,0 +1,13 @@
+/**
+ * ProcessPlan — the typed intermediate representation Claude (or any LLM)
+ * authors instead of BPMN XML. `compilePlan()` turns a plan into valid,
+ * laid-out, executable BPMN via the `@bpmnkit/core` builder; the model never
+ * touches XML, DI, element IDs, or connector property keys directly.
+ *
+ * Every string field documented as FEEL follows this SDK's existing
+ * convention throughout: a leading "=" makes it a FEEL expression, its
+ * absence makes it a literal string. This matches how `zeebe:input`/`output`
+ * `source` values already work in `@bpmnkit/core`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@bpmnkit/feel": "0.0.19"
+    "@bpmnkit/feel": "0.0.20"
   },
   "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
   "keywords": [