@bpmnkit/core 0.1.1 → 0.2.0

package/dist/node/write.js

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import { chmod, link, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { applyAutoLayout } from "../bpmn/auto-layout.js";
+import { parseBpmn } from "../bpmn/bpmn-parser.js";
+import { serializeBpmn } from "../bpmn/bpmn-serializer.js";
+import { diffSemantics, semanticHash } from "../bpmn/semantic-hash.js";
+import { sha256Hex } from "../bpmn/sha256.js";
+import { WriteError, WriteVerificationError } from "../errors.js";
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function isErrnoCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+/** Codes returned by filesystems that cannot make a hard link. */
+const NO_HARD_LINKS = new Set(["ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV", "EMLINK"]);
+/**
+ * Serialises a model, verifies it survives a round trip, and writes it
+ * atomically.
+ *
+ * The file appears complete or not at all: the contents go to a temporary file
+ * in the destination's own directory and are then renamed into place, so an
+ * interrupted write cannot leave a half-written model behind. Without `force`
+ * the final step is a hard link, which fails if the destination appeared in the
+ * meantime rather than silently replacing it.
+ *
+ * @param definitions - The model to write.
+ * @param options - Destination and write behaviour.
+ * @returns Where it went, what it hashes to, and what it changed.
+ * @throws {WriteVerificationError} If reading the output back does not
+ *   reproduce the model. Nothing is written.
+ * @throws {WriteError} If the destination exists and `force` was not given, or
+ *   the filesystem refused the write.
+ *
+ * @example
+ * ```typescript
+ * import { writeBpmn } from "@bpmnkit/core/node"
+ *
+ * const result = await writeBpmn(definitions, { output: "flow.bpmn" })
+ * console.log(result.semanticHash, result.changes?.changed.length ?? 0)
+ * ```
+ */
+export async function writeBpmn(definitions, options) {
+    const destination = resolve(options.output);
+    const force = options.force === true;
+    const exists = await pathExists(destination);
+    // Fail before doing the work, not after it.
+    if (exists && !force) {
+        throw new WriteError(`Refusing to overwrite ${options.output}. Pass force: true to replace it.`);
+    }
+    // applyAutoLayout returns a new model, so the caller's stays untouched.
+    const model = options.layout === "auto" ? applyAutoLayout(definitions) : definitions;
+    const expected = semanticHash(model);
+    const xml = serializeBpmn(model);
+    let reparsed;
+    try {
+        reparsed = parseBpmn(xml);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new WriteVerificationError(`Serialising the model produced BPMN that cannot be parsed back: ${reason}`, { added: [], removed: [], changed: [] });
+    }
+    const actual = semanticHash(reparsed);
+    if (actual !== expected) {
+        const changes = diffSemantics(model, reparsed);
+        throw new WriteVerificationError([
+            "Serialising the model did not reproduce it, so nothing was written.",
+            `Lost: ${changes.removed.join(", ") || "none"}.`,
+            `Added: ${changes.added.join(", ") || "none"}.`,
+            `Altered: ${changes.changed.map((entry) => entry.id).join(", ") || "none"}.`,
+        ].join(" "), changes);
+    }
+    const changes = exists ? await changesAgainst(destination, reparsed) : undefined;
+    await writeAtomically(destination, xml, force);
+    return {
+        destination,
+        bytes: Buffer.byteLength(xml, "utf-8"),
+        outputSha256: sha256Hex(xml),
+        semanticHash: actual,
+        changes,
+    };
+}
+/**
+ * Diffs the model about to be written against the one already on disk. A
+ * previous file that cannot be read or parsed yields no report rather than
+ * failing the write — the old contents are being replaced either way.
+ */
+async function changesAgainst(destination, next) {
+    try {
+        return diffSemantics(parseBpmn(await readFile(destination, "utf-8")), next);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeAtomically(destination, contents, force) {
+    const temporary = resolve(dirname(destination), `.${basename(destination)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, contents, { encoding: "utf-8", flag: "wx" });
+        if (force) {
+            // Keep the permissions the file already had; a rename would otherwise
+            // hand it whatever the temporary file was created with.
+            const mode = await modeOf(destination);
+            if (mode !== undefined)
+                await chmod(temporary, mode);
+            await rename(temporary, destination);
+            return;
+        }
+        await linkOrCreateExclusively(temporary, destination, contents);
+    }
+    catch (error) {
+        if (error instanceof WriteError)
+            throw error;
+        if (isErrnoCode(error, "EEXIST")) {
+            throw new WriteError(`Refusing to overwrite ${destination}: it appeared while writing. Pass force: true to replace it.`);
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new WriteError(`Unable to write ${destination}: ${reason}`);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/**
+ * Creates the destination without replacing anything. `link` fails with EEXIST
+ * if the destination is taken, which `rename` would not, and it publishes the
+ * already-complete temporary file in one step.
+ *
+ * Filesystems without hard links fall back to an exclusive create, which is
+ * still safe against replacing an existing file but writes in place rather than
+ * atomically — an interrupted write there can leave a partial file.
+ */
+async function linkOrCreateExclusively(temporary, destination, contents) {
+    try {
+        await link(temporary, destination);
+    }
+    catch (error) {
+        if (!isErrnoCode(error, "EEXIST") && isNoHardLinkSupport(error)) {
+            await writeFile(destination, contents, { encoding: "utf-8", flag: "wx" });
+            return;
+        }
+        throw error;
+    }
+}
+function isNoHardLinkSupport(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        NO_HARD_LINKS.has(error.code ?? ""));
+}
+async function modeOf(path) {
+    try {
+        return (await stat(path)).mode;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=write.js.map

package/dist/plan/compile.d.ts

@@ -0,0 +1,39 @@
+import type { AdHocSubProcessOptions, BoundaryEventOptions, IntermediateCatchEventOptions, ServiceTaskOptions, StartEventOptions } from "../bpmn/bpmn-builder.js";
+import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
+import type { ProcessPlan } from "./types.js";
+export interface PlanProblem {
+    /** A path into the plan, e.g. "steps[2].branches[0].condition", for pinpointing the offending field. */
+    path: string;
+    message: string;
+}
+export interface SynthResult {
+    defs?: BpmnDefinitions;
+    xml?: string;
+    problems: PlanProblem[];
+}
+/** What a connector template resolves to — structurally matches `@bpmnkit/connectors`' `ApplyResult`. */
+export interface ConnectorApplyResult {
+    serviceTask?: ServiceTaskOptions;
+    adHocSubProcess?: Partial<AdHocSubProcessOptions>;
+    startEvent?: Partial<StartEventOptions>;
+    boundaryEvent?: Partial<BoundaryEventOptions>;
+    intermediateEvent?: Partial<IntermediateCatchEventOptions>;
+    problems: Array<{
+        key?: string;
+        message: string;
+    }>;
+}
+export type ConnectorResolver = (templateId: string, values: Record<string, string>) => ConnectorApplyResult;
+export interface CompilePlanOptions {
+    /** Resolves `PlanConnectorRef`s — pass `applyConnectorTemplate` from `@bpmnkit/connectors`. Without it, connector steps produce a problem. */
+    resolveConnector?: ConnectorResolver;
+    /** Skip auto-applying safe optimizer fixes (default false). */
+    skipAutoFix?: boolean;
+}
+/**
+ * Compiles a `ProcessPlan` into laid-out, validated BPMN XML. Deterministic:
+ * the same plan always produces the same XML. Problems are collected, not
+ * thrown — check `result.problems` before using `result.xml`.
+ */
+export declare function compilePlan(plan: ProcessPlan, opts?: CompilePlanOptions): SynthResult;
+//# sourceMappingURL=compile.d.ts.map

package/dist/plan/compile.js

@@ -0,0 +1,380 @@
+import { parseExpression } from "@bpmnkit/feel";
+import { buildAiAgentSubProcess } from "../bpmn/agentic.js";
+import { applyAutoLayout } from "../bpmn/auto-layout.js";
+import { Bpmn } from "../bpmn/index.js";
+import { optimize } from "../bpmn/optimize/index.js";
+import { slugify, uniqueId } from "./slug.js";
+// ---------------------------------------------------------------------------
+// ID assignment — every step gets a stable id before any builder call is made,
+// so gateway branches can `connectTo()` the right target up front.
+// ---------------------------------------------------------------------------
+function assignIds(steps, taken, idOf) {
+    for (const step of steps) {
+        const base = step.id ?? slugify(step.name ?? step.kind);
+        idOf.set(step, uniqueId(base, taken));
+        if (step.errorBoundary)
+            assignIds(step.errorBoundary.steps, taken, idOf);
+        if (step.timerBoundary)
+            assignIds(step.timerBoundary.steps, taken, idOf);
+        if (step.kind === "gateway") {
+            for (const branch of step.branches)
+                assignIds(branch.steps, taken, idOf);
+        }
+        if (step.kind === "subProcess")
+            assignIds(step.steps, taken, idOf);
+    }
+}
+// ---------------------------------------------------------------------------
+// FEEL validation
+// ---------------------------------------------------------------------------
+function checkFeel(path, value, problems) {
+    if (!value || !value.startsWith("="))
+        return;
+    const { errors } = parseExpression(value.slice(1));
+    for (const err of errors) {
+        problems.push({ path, message: `Invalid FEEL expression: ${err.message}` });
+    }
+}
+// ---------------------------------------------------------------------------
+// Connector / agent tool resolution
+// ---------------------------------------------------------------------------
+function resolveConnectorOrProblem(ref, path, resolve, problems) {
+    if (!resolve) {
+        problems.push({
+            path,
+            message: `Step references connector template "${ref.template}" but no connector resolver was provided to compilePlan()`,
+        });
+        return undefined;
+    }
+    const result = resolve(ref.template, ref.values ?? {});
+    for (const p of result.problems) {
+        problems.push({ path: p.key ? `${path}.values.${p.key}` : path, message: p.message });
+    }
+    return result;
+}
+function toolServiceTaskOptions(tool, path, resolve, problems) {
+    if (tool.connector) {
+        const result = resolveConnectorOrProblem(tool.connector, path, resolve, problems);
+        if (result?.serviceTask)
+            return result.serviceTask;
+        return { name: tool.id, taskType: "" };
+    }
+    return { name: tool.id, taskType: tool.jobType ?? "" };
+}
+// ---------------------------------------------------------------------------
+// Step emission
+// ---------------------------------------------------------------------------
+function emitStep(b, step, id, path, nextId, idOf, resolve, problems) {
+    switch (step.kind) {
+        case "start":
+            // Handled by the caller — start steps are only valid as plan.steps[0].
+            return;
+        case "connector": {
+            const result = resolveConnectorOrProblem(step.connector, `${path}.connector`, resolve, problems);
+            b.serviceTask(id, {
+                ...(result?.serviceTask ?? { name: step.name ?? id, taskType: "" }),
+                documentation: step.documentation,
+                ...(step.retries ? { retries: step.retries } : {}),
+            });
+            return;
+        }
+        case "serviceTask": {
+            const inputs = Object.entries(step.inputs ?? {}).map(([target, source]) => ({
+                source,
+                target,
+            }));
+            const outputs = Object.entries(step.outputs ?? {}).map(([target, source]) => ({
+                source,
+                target,
+            }));
+            for (const [k, v] of Object.entries(step.inputs ?? {}))
+                checkFeel(`${path}.inputs.${k}`, v, problems);
+            for (const [k, v] of Object.entries(step.outputs ?? {}))
+                checkFeel(`${path}.outputs.${k}`, v, problems);
+            b.serviceTask(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                taskType: step.jobType,
+                retries: step.retries,
+                taskHeaders: step.taskHeaders,
+                ioMapping: inputs.length || outputs.length ? { inputs, outputs } : undefined,
+            });
+            return;
+        }
+        case "userTask":
+            b.userTask(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                zeebeUserTask: true,
+                formId: step.formId,
+                assignee: step.assignee,
+                candidateGroups: step.candidateGroups,
+                candidateUsers: step.candidateUsers,
+                dueDate: step.dueDate,
+                followUpDate: step.followUpDate,
+                priority: step.priority,
+            });
+            return;
+        case "businessRuleTask":
+            b.businessRuleTask(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                decisionId: step.decisionId,
+                resultVariable: step.resultVariable,
+            });
+            return;
+        case "scriptTask":
+            checkFeel(`${path}.expression`, step.expression, problems);
+            b.scriptTask(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                expression: step.expression,
+                resultVariable: step.resultVariable,
+            });
+            return;
+        case "sendTask":
+            b.sendTask(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                messageName: step.messageName,
+            });
+            return;
+        case "receiveTask":
+            b.receiveTask(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                messageName: step.messageName,
+                correlationKey: step.correlationKey,
+            });
+            return;
+        case "callActivity":
+            b.callActivity(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                processId: step.processId,
+                propagateAllChildVariables: step.propagateAllChildVariables,
+            });
+            return;
+        case "aiAgent": {
+            checkFeel(`${path}.systemPrompt`, step.systemPrompt, problems);
+            checkFeel(`${path}.userPrompt`, step.userPrompt, problems);
+            checkFeel(`${path}.completionCondition`, step.completionCondition, problems);
+            if (step.tools.length === 0) {
+                problems.push({ path: `${path}.tools`, message: "aiAgent step has no tools" });
+            }
+            const agent = buildAiAgentSubProcess({
+                id,
+                name: step.name,
+                model: {
+                    provider: step.provider,
+                    inputs: { [`provider.${step.provider}.model.model`]: step.model, ...step.providerInputs },
+                },
+                systemPrompt: step.systemPrompt,
+                userPrompt: step.userPrompt,
+                memoryStorageType: step.memoryStorageType,
+                maxModelCalls: step.maxModelCalls,
+                outputVariable: step.outputVariable,
+                retries: step.retries,
+                completionCondition: step.completionCondition,
+                cancelRemainingInstances: step.cancelRemainingInstances,
+                tools: step.tools.map((tool) => ({
+                    id: tool.id,
+                    description: tool.description,
+                    serviceTask: toolServiceTaskOptions(tool, `${path}.tools[${tool.id}]`, resolve, problems),
+                    params: (tool.params ?? []).map((p) => ({
+                        name: p.name,
+                        description: p.description,
+                        type: p.type,
+                        required: p.required,
+                        schema: p.schema,
+                        target: p.target ?? p.name,
+                    })),
+                    resultSource: tool.resultExpression,
+                })),
+            });
+            b.adHocSubProcess(id, agent.content, agent.options);
+            return;
+        }
+        case "gateway": {
+            const gwOptions = { name: step.name, documentation: step.documentation };
+            switch (step.gatewayType) {
+                case "exclusive":
+                    b.exclusiveGateway(id, gwOptions);
+                    break;
+                case "parallel":
+                    b.parallelGateway(id, gwOptions);
+                    break;
+                case "inclusive":
+                    b.inclusiveGateway(id, gwOptions);
+                    break;
+                case "eventBased":
+                    b.eventBasedGateway(id, gwOptions);
+                    break;
+            }
+            for (let bi = 0; bi < step.branches.length; bi++) {
+                const branch = step.branches[bi];
+                checkFeel(`${path}.branches[${bi}].condition`, branch.condition, problems);
+                b.branch(branch.name ?? `branch_${bi + 1}`, (bb) => {
+                    if (branch.default)
+                        bb.defaultFlow();
+                    else if (branch.condition)
+                        bb.condition(branch.condition);
+                    emitSteps(bb, branch.steps, idOf, resolve, problems, `${path}.branches[${bi}].steps`);
+                    if (nextId)
+                        bb.connectTo(nextId);
+                });
+            }
+            return;
+        }
+        case "subProcess":
+            b.subProcess(id, (sb) => emitSteps(sb, step.steps, idOf, resolve, problems, `${path}.steps`), {
+                name: step.name,
+                documentation: step.documentation,
+                multiInstance: step.multiInstance
+                    ? {
+                        isSequential: step.multiInstance.isSequential,
+                        collection: step.multiInstance.collection,
+                        elementVariable: step.multiInstance.elementVariable,
+                        completionCondition: step.multiInstance.completionCondition,
+                    }
+                    : undefined,
+            });
+            return;
+        case "wait":
+            checkFeel(`${path}.message.correlationKey`, step.message?.correlationKey, problems);
+            b.intermediateCatchEvent(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                timerDuration: step.timer?.duration,
+                timerDate: step.timer?.date,
+                timerCycle: step.timer?.cycle,
+                messageName: step.message?.name,
+                correlationKey: step.message?.correlationKey,
+            });
+            return;
+        case "end":
+            b.endEvent(id, {
+                name: step.name ?? id,
+                documentation: step.documentation,
+                errorCode: step.errorCode,
+            });
+            return;
+        case "raw":
+            problems.push({
+                path,
+                message: `"raw" steps are not yet compiled — element type "${step.elementType}" was skipped`,
+            });
+            return;
+    }
+}
+function emitBoundaries(b, step, id, path, idOf, resolve, problems) {
+    if (step.errorBoundary) {
+        b.withBoundary(`${id}_error`, {
+            errorCode: step.errorBoundary.errorCode,
+            cancelActivity: step.errorBoundary.interrupting ?? true,
+        }, (hb) => emitSteps(hb, step.errorBoundary.steps, idOf, resolve, problems, `${path}.errorBoundary.steps`));
+    }
+    if (step.timerBoundary) {
+        b.withBoundary(`${id}_timer`, {
+            timerDuration: step.timerBoundary.duration,
+            timerDate: step.timerBoundary.date,
+            timerCycle: step.timerBoundary.cycle,
+            cancelActivity: step.timerBoundary.interrupting ?? true,
+        }, (hb) => emitSteps(hb, step.timerBoundary.steps, idOf, resolve, problems, `${path}.timerBoundary.steps`));
+    }
+}
+function emitSteps(b, steps, idOf, resolve, problems, path, indexOffset = 0) {
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const id = idOf.get(step);
+        if (!id)
+            continue;
+        const stepPath = `${path}[${i + indexOffset}]`;
+        const nextStep = steps[i + 1];
+        const nextId = nextStep ? idOf.get(nextStep) : undefined;
+        emitStep(b, step, id, stepPath, nextId, idOf, resolve, problems);
+        emitBoundaries(b, step, id, stepPath, idOf, resolve, problems);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Compiles a `ProcessPlan` into laid-out, validated BPMN XML. Deterministic:
+ * the same plan always produces the same XML. Problems are collected, not
+ * thrown — check `result.problems` before using `result.xml`.
+ */
+export function compilePlan(plan, opts = {}) {
+    const problems = [];
+    if (plan.version !== 1) {
+        problems.push({ path: "version", message: `Unsupported plan version ${String(plan.version)}` });
+        return { problems };
+    }
+    if (!plan.process?.id) {
+        problems.push({ path: "process.id", message: "process.id is required" });
+        return { problems };
+    }
+    if (!plan.steps || plan.steps.length === 0) {
+        problems.push({ path: "steps", message: "Plan has no steps" });
+        return { problems };
+    }
+    const [firstStep, ...restSteps] = plan.steps;
+    if (!firstStep || firstStep.kind !== "start") {
+        problems.push({ path: "steps[0]", message: 'The first step must have kind "start"' });
+        return { problems };
+    }
+    const taken = new Set();
+    const idOf = new Map();
+    assignIds(plan.steps, taken, idOf);
+    const builder = Bpmn.createProcess(plan.process.id);
+    if (plan.process.name)
+        builder.name(plan.process.name);
+    if (plan.process.versionTag)
+        builder.versionTag(plan.process.versionTag);
+    let startResult;
+    if (firstStep.connector) {
+        startResult = resolveConnectorOrProblem(firstStep.connector, "steps[0].connector", opts.resolveConnector, problems);
+    }
+    const startId = idOf.get(firstStep);
+    builder.startEvent(startId, {
+        name: firstStep.name ?? "Start",
+        documentation: firstStep.documentation,
+        timerDuration: firstStep.timer?.duration,
+        timerDate: firstStep.timer?.date,
+        timerCycle: firstStep.timer?.cycle,
+        messageName: firstStep.message?.name,
+        zeebeProperties: startResult?.startEvent?.zeebeProperties,
+    });
+    emitSteps(builder, restSteps, idOf, opts.resolveConnector, problems, "steps", 1);
+    let defs;
+    try {
+        defs = builder.build();
+    }
+    catch (err) {
+        problems.push({
+            path: "steps",
+            message: `Build failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return { problems };
+    }
+    let laidOut = applyAutoLayout(defs);
+    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,
+            });
+        }
+    }
+    const xml = Bpmn.export(laidOut);
+    return { defs: laidOut, xml, problems };
+}
+//# sourceMappingURL=compile.js.map

package/dist/plan/extract.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lifts an existing `BpmnDefinitions` process back into `ProcessPlan` form,
+ * so `/bpmnkit:extend`-style skills can express a delta instead of
+ * regenerating a whole process.
+ *
+ * Scope (documented, not silently exceeded): linear chains of tasks/events,
+ * plus a single level of exclusive/parallel/inclusive gateway branches that
+ * reconverge to a common next element. Sub-processes, ad-hoc sub-processes
+ * (including AI Agent sub-processes), nested gateways, pools/lanes, and data
+ * objects are not lifted — they are reported in `unsupported` rather than
+ * silently dropped or guessed at. Use `mergePlan()` to add new steps to a
+ * process without needing to fully extract it first.
+ */
+import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
+import type { ProcessPlan } from "./types.js";
+export interface UnsupportedElement {
+    id: string;
+    type: string;
+    reason: string;
+}
+export interface ExtractResult {
+    plan: ProcessPlan;
+    unsupported: UnsupportedElement[];
+}
+/**
+ * Extracts a single BPMN process into `ProcessPlan` form. Handles linear
+ * chains and a single level of gateway branching that reconverges; anything
+ * else is listed in `unsupported`, not fabricated.
+ */
+export declare function extractPlan(defs: BpmnDefinitions, processId?: string): ExtractResult;
+//# sourceMappingURL=extract.d.ts.map