@nanobpm/workflow 0.4.0 → 0.5.0

package/README.md

@@ -183,7 +183,25 @@ once.
 | `externalJobTypes(flow)` | The job types of a flow's external `task` steps (each overridable per-step via `w.task(name, { jobType })`). |
 | `WorkflowClient` | `deploy`, `start`, `signal`, `getInstance` over REST v2. |
 | `Worker` | Generic job runtime; routes job types → handlers, hosts the replay loop. |
-| `toBpmn(workflow)` | The derived BPMN XML (for inspection / deployment). |
+| `toBpmn(workflow)` | The DI-less semantic BPMN the engine runs (for inspection / deployment). |
+| `toDeployableBpmn(workflow, { layout? })` | The deployable BPMN **with an auto-generated diagram (DI)** so the deployed model is inspectable; what `deploy` sends by default. |
+| `layoutBpmn(xml)` / `declarativeToLayoutedBpmn(flow)` | Add DI to a model with `bpmn-auto-layout`. |
+
+### Inspectable deployments (diagram layout)
+
+`client.deploy(flow)` deploys the model **with an auto-generated diagram
+interchange (DI)** so it opens rendered and inspectable in a modeller/Operate
+rather than as a blank canvas. DI is generated with the optional peer dependency
+[`bpmn-auto-layout`](https://www.npmjs.com/package/bpmn-auto-layout):
+
+```sh
+npm i bpmn-auto-layout
+```
+
+If it is not installed, `deploy` degrades gracefully — it warns once and deploys
+the DI-less model. Pass `deploy(flow, { layout: false })` to skip layout
+deliberately. The semantic model stays authoritative; DI is derived and
+regenerable.
 
 See [ADR 0044](../docs/adr/0044-code-first-durable-orchestration.md) for the design
 rationale and [ADR 0047](../docs/adr/0047-declarative-flow-control-and-typed-envelopes.md)

package/dist/client.d.ts

@@ -1,6 +1,21 @@
 import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
 /** Render a workflow (either surface) to its executable BPMN model. */
 export declare function toBpmn(wf: Workflow): string;
+/**
+ * Render a workflow to *deployable* BPMN — the executable model plus diagram
+ * interchange (DI), auto-generated with `bpmn-auto-layout` — so the deployed
+ * process opens rendered and inspectable in a modeller/Operate rather than as a
+ * blank canvas. The semantic model stays authoritative; DI is derived.
+ *
+ * DI generation needs the optional peer dependency `bpmn-auto-layout`. When it is
+ * absent, this degrades gracefully: it warns once and returns the DI-less model
+ * so `deploy` still works everywhere. Pass `{ layout: false }` to skip layout
+ * deliberately. A genuine layout failure (the dep is installed but errors) is
+ * surfaced, not swallowed.
+ */
+export declare function toDeployableBpmn(wf: Workflow, opts?: {
+    layout?: boolean;
+}): Promise<string>;
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface WorkflowClientOptions {
     /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. */
@@ -29,8 +44,16 @@ export declare class WorkflowClient {
     /** Perform a request, throwing WorkflowError on transport error or !ok, and
      *  return the raw Response (for endpoints with an empty/no-content body). */
     private send;
-    /** Deploy a workflow's derived BPMN model. */
-    deploy(wf: Workflow): Promise<DeployResult>;
+    /**
+     * Deploy a workflow's derived BPMN model. The deployed model includes
+     * auto-generated diagram interchange (DI) so it is inspectable in a
+     * modeller/Operate; pass `{ layout: false }` to deploy the DI-less semantic
+     * model. DI needs the optional `bpmn-auto-layout` dependency — see
+     * `toDeployableBpmn` for the graceful-degradation behaviour when it is absent.
+     */
+    deploy(wf: Workflow, opts?: {
+        layout?: boolean;
+    }): Promise<DeployResult>;
     /**
      * Start a workflow instance. For imperative workflows the engine variables are
      * seeded with `{ input, journal: {}, wfDone: false }` (the replay state); for

package/dist/client.js

@@ -3,12 +3,50 @@
 // low-level job activate/complete/fail used by the Worker runtime.
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
+import { layoutBpmn } from "./layout.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
 /** Render a workflow (either surface) to its executable BPMN model. */
 export function toBpmn(wf) {
     assertWorkflowIds(wf);
     return wf.kind === "imperative" ? imperativeToBpmn(wf) : declarativeToBpmn(wf);
 }
+let warnedNoLayout = false;
+/**
+ * Render a workflow to *deployable* BPMN — the executable model plus diagram
+ * interchange (DI), auto-generated with `bpmn-auto-layout` — so the deployed
+ * process opens rendered and inspectable in a modeller/Operate rather than as a
+ * blank canvas. The semantic model stays authoritative; DI is derived.
+ *
+ * DI generation needs the optional peer dependency `bpmn-auto-layout`. When it is
+ * absent, this degrades gracefully: it warns once and returns the DI-less model
+ * so `deploy` still works everywhere. Pass `{ layout: false }` to skip layout
+ * deliberately. A genuine layout failure (the dep is installed but errors) is
+ * surfaced, not swallowed.
+ */
+export async function toDeployableBpmn(wf, opts = {}) {
+    const semantic = toBpmn(wf);
+    if (opts.layout === false)
+        return semantic;
+    try {
+        return await layoutBpmn(semantic);
+    }
+    catch (e) {
+        // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
+        // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
+        // problem and must surface rather than silently deploy an uninspectable model.
+        const cause = e?.cause;
+        if (cause?.code !== "ERR_MODULE_NOT_FOUND")
+            throw e;
+        if (!warnedNoLayout) {
+            warnedNoLayout = true;
+            console.warn(`[@nanobpm/workflow] Deploying "${wf.id}" without a diagram: the optional ` +
+                '"bpmn-auto-layout" dependency is not installed, so the model will be ' +
+                "uninspectable in a modeller/Operate. Install it for diagram layout: " +
+                "npm i bpmn-auto-layout");
+        }
+        return semantic;
+    }
+}
 export class WorkflowError extends Error {
     status;
     body;
@@ -51,9 +89,15 @@ export class WorkflowClient {
         }
         return res;
     }
-    /** Deploy a workflow's derived BPMN model. */
-    async deploy(wf) {
-        const xml = toBpmn(wf);
+    /**
+     * Deploy a workflow's derived BPMN model. The deployed model includes
+     * auto-generated diagram interchange (DI) so it is inspectable in a
+     * modeller/Operate; pass `{ layout: false }` to deploy the DI-less semantic
+     * model. DI needs the optional `bpmn-auto-layout` dependency — see
+     * `toDeployableBpmn` for the graceful-degradation behaviour when it is absent.
+     */
+    async deploy(wf, opts = {}) {
+        const xml = await toDeployableBpmn(wf, opts);
         const form = new FormData();
         form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
         return this.json(`/v2/deployments`, { method: "POST", body: form }, "deploy");

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { FlowBuilder } from "./declarative.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type { Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, ScalarTs, FieldTs, } from "./envelope.js";
-export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";

package/dist/index.js

@@ -42,5 +42,5 @@ export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
-export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
 export { Worker } from "./worker.js";

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway over the REST v2 API.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Magikcraft/nano-bpm",
-    "directory": "workflow"
+    "url": "https://github.com/jwulf/nano-ide.git",
+    "directory": "packages/workflow"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/client.ts

@@ -4,6 +4,7 @@
 
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
+import { layoutBpmn } from "./layout.js";
 import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
 
@@ -13,6 +14,47 @@ export function toBpmn(wf: Workflow): string {
   return wf.kind === "imperative" ? imperativeToBpmn(wf) : declarativeToBpmn(wf);
 }
 
+let warnedNoLayout = false;
+
+/**
+ * Render a workflow to *deployable* BPMN — the executable model plus diagram
+ * interchange (DI), auto-generated with `bpmn-auto-layout` — so the deployed
+ * process opens rendered and inspectable in a modeller/Operate rather than as a
+ * blank canvas. The semantic model stays authoritative; DI is derived.
+ *
+ * DI generation needs the optional peer dependency `bpmn-auto-layout`. When it is
+ * absent, this degrades gracefully: it warns once and returns the DI-less model
+ * so `deploy` still works everywhere. Pass `{ layout: false }` to skip layout
+ * deliberately. A genuine layout failure (the dep is installed but errors) is
+ * surfaced, not swallowed.
+ */
+export async function toDeployableBpmn(
+  wf: Workflow,
+  opts: { layout?: boolean } = {},
+): Promise<string> {
+  const semantic = toBpmn(wf);
+  if (opts.layout === false) return semantic;
+  try {
+    return await layoutBpmn(semantic);
+  } catch (e) {
+    // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
+    // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
+    // problem and must surface rather than silently deploy an uninspectable model.
+    const cause = (e as { cause?: NodeJS.ErrnoException })?.cause;
+    if (cause?.code !== "ERR_MODULE_NOT_FOUND") throw e;
+    if (!warnedNoLayout) {
+      warnedNoLayout = true;
+      console.warn(
+        `[@nanobpm/workflow] Deploying "${wf.id}" without a diagram: the optional ` +
+          '"bpmn-auto-layout" dependency is not installed, so the model will be ' +
+          "uninspectable in a modeller/Operate. Install it for diagram layout: " +
+          "npm i bpmn-auto-layout",
+      );
+    }
+    return semantic;
+  }
+}
+
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 
 export interface WorkflowClientOptions {
@@ -75,9 +117,15 @@ export class WorkflowClient {
     return res;
   }
 
-  /** Deploy a workflow's derived BPMN model. */
-  async deploy(wf: Workflow): Promise<DeployResult> {
-    const xml = toBpmn(wf);
+  /**
+   * Deploy a workflow's derived BPMN model. The deployed model includes
+   * auto-generated diagram interchange (DI) so it is inspectable in a
+   * modeller/Operate; pass `{ layout: false }` to deploy the DI-less semantic
+   * model. DI needs the optional `bpmn-auto-layout` dependency — see
+   * `toDeployableBpmn` for the graceful-degradation behaviour when it is absent.
+   */
+  async deploy(wf: Workflow, opts: { layout?: boolean } = {}): Promise<DeployResult> {
+    const xml = await toDeployableBpmn(wf, opts);
     const form = new FormData();
     form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
     return this.json<DeployResult>(`/v2/deployments`, { method: "POST", body: form }, "deploy");

package/src/index.ts

@@ -54,7 +54,7 @@ export type {
   ScalarTs,
   FieldTs,
 } from "./envelope.js";
-export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";