@nanobpm/nano-workforce 0.125.0 → 0.126.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.126.0](https://github.com/nanobpm/nano-workforce/compare/v0.125.0...v0.126.0) (2026-08-23)
+
+
+### Features
+
+* **delivery-graphs:** preview a staged proposal's generated DI, zero deploy ([#469](https://github.com/nanobpm/nano-workforce/issues/469)) ([c275d72](https://github.com/nanobpm/nano-workforce/commit/c275d7279d8a46d1ca8ce82e366016ca7ef0a22f)), closes [Magikcraft/nano-bpm#972](https://github.com/Magikcraft/nano-bpm/issues/972)
+
 # [0.125.0](https://github.com/nanobpm/nano-workforce/compare/v0.124.0...v0.125.0) (2026-08-23)
 
 

package/openapi.yaml

@@ -1548,6 +1548,44 @@ components:
           type: string
           maxLength: 255
           description: OPTIONAL idempotency key. A re-dispatch with the same key (or, when omitted, the same digest) does not double-launch. Blank/whitespace is treated as absent.
+    DeliveryGraphProposalBpmnRequest:
+      description: >-
+        Request the compiled BPMN of a staged delivery-graph proposal for read-only DI PREVIEW. Carries
+        only the proposal's content `digest`; the door recompiles the staged graph deterministically. No
+        deploy, no dispatch — this reads, it does not launch anything.
+      type: object
+      additionalProperties: false
+      required:
+        - digest
+      properties:
+        digest:
+          type: string
+          description: The staged proposal's content digest — the proposal whose compiled BPMN (with DI) to render.
+    DeliveryGraphProposalBpmnResult:
+      description: >-
+        The compiled BPMN of a staged proposal, for read-only DI preview. `ok` discriminates success; a
+        failure (unknown/expired/superseded/dispatched digest, corrupt or no-longer-compiling graph)
+        carries a human `error`.
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+      properties:
+        ok:
+          type: boolean
+          description: True when the staged graph recompiled and its BPMN is returned; false otherwise.
+        error:
+          type: string
+          description: A human-readable failure message.
+        digest:
+          type: string
+          description: The proposal's content digest, echoed on success.
+        bpmn:
+          type: string
+          description: >-
+            The compiled BPMN 2.0 XML INCLUDING diagram interchange (`bpmndi:BPMNDiagram`), recompiled
+            deterministically from the staged graph — byte-identical to what a dispatch would deploy.
+            Rendered read-only in the host explorer's definition preview. Nothing is deployed.
     DeliveryGraphTextResult:
       description: >-
         The delivery-graph text-ingress outcome (issue #460) — a single shape covering the JSON-paste
@@ -2752,6 +2790,36 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DeliveryGraphTextResult"
+  /actions/delivery-graph/proposal-bpmn:
+    post:
+      operationId: previewProposalBpmn
+      summary: Recompile a staged delivery-graph proposal's BPMN (with DI) for read-only preview — no deploy, no dispatch.
+      description: >-
+        Return the compiled BPMN 2.0 XML (including diagram interchange) of a staged delivery-graph
+        proposal, so its generated DI can be previewed BEFORE dispatch. The cockpit posts the proposal's
+        `digest`; this door loads that `staged` proposal and recompiles its stored graph deterministically
+        (the recompiled digest must equal the requested one), returning the BPMN. It NEVER deploys a
+        definition or launches an instance — it is a pure read. An unknown / expired / superseded /
+        already-dispatched digest, or a graph that no longer compiles, is a clean 400.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphProposalBpmnRequest"
+      responses:
+        "200":
+          description: The staged proposal recompiled; the body carries its BPMN (with DI).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphProposalBpmnResult"
+        "400":
+          description: The digest was missing, named no live staged proposal, or the stored graph failed to recompile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphProposalBpmnResult"
   /actions/start/feature:
     post:
       operationId: startFeature

package/operations/previewProposalBpmn.test.ts

@@ -0,0 +1,93 @@
+// Integration coverage for POST /app/api/actions/delivery-graph/proposal-bpmn operation
+// `previewProposalBpmn` — the READ-ONLY DI preview door. The cockpit posts a staged proposal's
+// `digest`; this door recompiles that staged graph and returns the compiled BPMN (with DI) so the host
+// explorer can render the generated diagram interchange BEFORE dispatch. It deploys nothing and
+// launches nothing. These tests drive the REAL door through `bootTestApp`'s api driver: stage via the
+// compile door, then preview by digest, asserting the BPMN carries DI and that an unknown/blank digest
+// is refused cleanly.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
+
+const SIDE_EFFECTING = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [{ from: "open-b", to: "cut" }],
+};
+
+describe("previewProposalBpmn — read-only DI preview of a staged proposal", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+  const boot = async (): Promise<TestApp> => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-preview-bpmn-"));
+    dirs.push(d);
+    const app = await bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(d, "app.db")}` } });
+    apps.push(app);
+    return app;
+  };
+
+  test("a missing/blank digest → 400 with a human error", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const res = await app.api.call<{ ok: boolean; error?: string }>("previewProposalBpmn", { body: { digest: "  " } });
+    assert.equal(res.status, 400);
+    assert.equal(res.body.ok, false);
+    assert.ok(typeof res.body.error === "string" && res.body.error.length > 0);
+  });
+
+  test("an unknown / never-staged digest → 400", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const res = await app.api.call<{ ok: boolean; error?: string }>("previewProposalBpmn", { body: { digest: "deadbeef0000" } });
+    assert.equal(res.status, 400);
+    assert.equal(res.body.ok, false);
+    assert.ok(/no staged proposal/.test(res.body.error ?? ""));
+  });
+
+  test("a staged graph: preview by digest → 200 with BPMN carrying DI; nothing deployed or launched", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
+    assert.equal(staged.status, 200);
+    const digest = staged.body.digest;
+
+    const res = await api.call<{ ok: boolean; digest?: string; bpmn?: string }>("previewProposalBpmn", { body: { digest } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.digest, digest);
+    const bpmn = res.body.bpmn ?? "";
+    // The returned BPMN carries diagram interchange (this is the whole point — a renderable DI).
+    assert.ok(bpmn.includes("<bpmndi:BPMNDiagram"), "BPMN must include diagram interchange");
+    assert.ok(bpmn.includes("bpmn:definitions") || bpmn.includes("<definitions"), "BPMN must be a definitions doc");
+    // Pure read: no run was launched.
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+  });
+
+  test("preview is deterministic — the same digest returns byte-identical BPMN across calls", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
+    const digest = staged.body.digest;
+    const a = await api.call<{ bpmn?: string }>("previewProposalBpmn", { body: { digest } });
+    const b = await api.call<{ bpmn?: string }>("previewProposalBpmn", { body: { digest } });
+    assert.equal(a.body.bpmn, b.body.bpmn);
+  });
+});

package/operations/previewProposalBpmn.ts

@@ -0,0 +1,96 @@
+// POST /app/api/actions/delivery-graph/proposal-bpmn → operationId `previewProposalBpmn`.
+// The READ-ONLY DI preview door: the cockpit's staged-proposals grid posts the `digest` of the
+// proposal the operator wants to look at, and this door recompiles that staged graph and hands back the
+// compiled BPMN (with `bpmndi:BPMNDiagram`) so the host explorer can render the generated diagram
+// interchange BEFORE dispatch.
+//
+// It is a PURE READ: no deploy, no dispatch, no instance — the compiler is deterministic (same graph →
+// byte-identical BPMN → same digest), so we recompile the stored graph on demand rather than persisting
+// the BPMN. As a determinism guard, the recompiled digest MUST equal the requested one; a mismatch means
+// the stored graph and its content-address have drifted, which we surface as a 400 rather than serving a
+// diagram that doesn't match the digest the operator is about to dispatch.
+//
+// An unknown / expired / superseded / already-dispatched digest, or a graph that no longer compiles, is a
+// clean 400 (never a 500).
+
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import { getStagedProposal } from "../app/deliveryGraphProposals.ts";
+import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import type { DeliveryGraphProposalBpmnResult } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("previewProposalBpmn", async ({ body }, app) => {
+  const digest = typeof body?.digest === "string" ? body.digest.trim() : "";
+  if (digest === "") {
+    app.log.warn("preview-proposal-bpmn rejected: missing digest");
+    return {
+      status: 400,
+      body: { ok: false, error: "request body must carry a `digest` naming the staged proposal to preview" },
+    };
+  }
+
+  // Refuses an unknown / expired / superseded / already-dispatched digest cleanly.
+  const proposal = await getStagedProposal(app.data, digest);
+  if (!proposal) {
+    app.log.warn("preview-proposal-bpmn rejected: no live staged proposal", { digest });
+    return {
+      status: 400,
+      body: {
+        ok: false,
+        error: `no staged proposal for digest ${digest} — it may have been dispatched, superseded, or aged out; recompile to re-stage it`,
+      },
+    };
+  }
+
+  let graph: unknown;
+  try {
+    graph = JSON.parse(proposal.graph);
+  } catch (err) {
+    app.log.error("preview-proposal-bpmn: stored graph is corrupt", { digest });
+    return {
+      status: 400,
+      body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` },
+    };
+  }
+
+  // Recompile the staged graph — the SAME pure compiler the agent/preview/dispatch doors use, so the
+  // BPMN (and its DI) is identical to what a dispatch would deploy. No side effects. The compiler can
+  // THROW (e.g. layout fails to emit a `<bpmndi:BPMNDiagram>`), which must stay a clean 400 per the door
+  // contract — never a bubbled 500.
+  let compiled: Awaited<ReturnType<typeof compileDeliveryGraph>>;
+  try {
+    compiled = await compileDeliveryGraph(graph);
+  } catch (err) {
+    app.log.warn("preview-proposal-bpmn: staged graph threw during recompile", { digest });
+    return {
+      status: 400,
+      body: {
+        ok: false,
+        error: `staged proposal ${digest} failed to recompile: ${err instanceof Error ? err.message : String(err)}`,
+      },
+    };
+  }
+  if (!compiled.ok) {
+    app.log.warn("preview-proposal-bpmn: staged graph no longer compiles", { digest, errors: compiled.errors.length });
+    return {
+      status: 400,
+      body: { ok: false, error: `staged proposal ${digest} failed to recompile: ${compiled.errors.length} error(s)` },
+    };
+  }
+
+  // Determinism guard: the recompiled BPMN must content-address back to the requested digest. A mismatch
+  // means the stored graph drifted from its digest — refuse rather than serve a diagram that doesn't
+  // match the proposal the operator is about to dispatch.
+  const recompiledDigest = deliveryGraphDigest(compiled.bpmn);
+  if (recompiledDigest !== digest) {
+    app.log.error("preview-proposal-bpmn: digest drift", { digest, recompiledDigest });
+    return {
+      status: 400,
+      body: { ok: false, error: `staged proposal ${digest} recompiled to a different digest (${recompiledDigest}) — the stored graph has drifted; recompile to re-stage it` },
+    };
+  }
+
+  app.log.info("preview-proposal-bpmn served", { digest, bytes: compiled.bpmn.length });
+  const out: DeliveryGraphProposalBpmnResult = { ok: true, digest, bpmn: compiled.bpmn };
+  return { status: 200, body: out };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.125.0",
+  "version": "0.126.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/delivery-graphs/mount.js

@@ -21,6 +21,9 @@
 //     graph is STAGED as a proposal (an operator dispatches it from the Staged proposals grid below).
 
 const DEFAULT_PREVIEW_URL = "app/api/actions/delivery-graph/preview";
+// The read-only DI preview door: recompiles a staged proposal's BPMN (with diagram interchange) so its
+// generated diagram can be rendered in the host explorer BEFORE dispatch. No deploy, no dispatch.
+const DEFAULT_PROPOSAL_BPMN_URL = "app/api/actions/delivery-graph/proposal-bpmn";
 
 // A bounded timeout for every door request. Without it a hung preview endpoint leaves the fetch
 // promise pending forever, so the busy() lock never clears and the UI is stranded (buttons disabled,
@@ -143,10 +146,14 @@ function renderPreview(result) {
       <span class="chip">Side effects <b>${esc(result.sideEffectCount)}</b></span>
       <span class="chip">Digest <code>${esc(result.digest)}</code></span>
     </div>
+    <div class="actions">
+      <button class="btn btn-ghost" type="button" data-preview-di="${esc(result.digest)}">Preview generated DI</button>
+      <span class="muted">the real laid-out BPMN, exactly as a dispatch would run it</span>
+    </div>
   </section>`;
   const diagram = `<section class="card">
     <h2>Diagram <span class="muted">(mermaid flowchart source)</span></h2>
-    <p class="muted">The resolved graph as a mermaid <code>flowchart</code>. Paste it into any mermaid renderer, or follow a dispatched run into the process explorer for the live laid-out model.</p>
+    <p class="muted">The resolved graph as a mermaid <code>flowchart</code>. Paste it into any mermaid renderer, or click <b>Preview generated DI</b> above to render the laid-out BPMN in the process explorer.</p>
     <pre class="diagram">${esc(result.diagram)}</pre>
   </section>`;
   return summary + renderSideEffects(result.sideEffects) + renderHumanNodes(result.humanNodes) + diagram;
@@ -155,7 +162,7 @@ function renderPreview(result) {
 /**
  * Mount the compose → preview → stage view into `host`.
  * @param {Element|null} host — the element to render into (or null → look up #delivery-graphs-root).
- * @param {{previewUrl?:string, hookSecret?:string}} [config]
+ * @param {{previewUrl?:string, proposalBpmnUrl?:string, hookSecret?:string}} [config]
  */
 export function mountDeliveryGraphs(host, config = {}) {
   const isElement = host != null && host.nodeType === 1 && typeof host.innerHTML === "string";
@@ -163,6 +170,7 @@ export function mountDeliveryGraphs(host, config = {}) {
   if (!root) return () => {};
 
   const previewUrl = config.previewUrl ?? DEFAULT_PREVIEW_URL;
+  const proposalBpmnUrl = config.proposalBpmnUrl ?? DEFAULT_PROPOSAL_BPMN_URL;
   const headers = () => ({
     "content-type": "application/json",
     ...(config.hookSecret ? { "x-hook-secret": config.hookSecret } : {}),
@@ -259,6 +267,49 @@ export function mountDeliveryGraphs(host, config = {}) {
     setStatus("Example loaded — Preview & stage it.", "");
   });
 
+  // "Preview generated DI": recompile the staged proposal's BPMN (with diagram interchange) and hand it
+  // to the host console's process explorer, which renders it read-only in a definition-preview view.
+  // We run inside the console App-View iframe, so we fetch from our OWN nwf door (same origin as this
+  // app) and pass the XML UP to the console over the nano-navigate bridge — the XML is far larger than a
+  // URL budget, so it travels in the message, not the path. Standalone (not embedded) there is no host
+  // explorer to drive, so we say so instead of failing silently.
+  const isEmbedded = typeof window !== "undefined" && window.parent && window.parent !== window;
+  async function doPreviewDi(digest) {
+    const staged = typeof digest === "string" ? digest.trim() : "";
+    if (staged === "") {
+      setStatus("No staged proposal to preview yet — Preview & stage a graph first.", "err");
+      return;
+    }
+    if (!isEmbedded) {
+      setStatus("Open this page inside the console cockpit to preview the generated DI.", "err");
+      return;
+    }
+    busy(true);
+    setStatus("Compiling DI…");
+    try {
+      const { status, body } = await post(proposalBpmnUrl, { digest: staged });
+      if (status === 200 && body.ok && typeof body.bpmn === "string" && body.bpmn.trim() !== "") {
+        window.parent.postMessage(
+          { type: "nano-navigate", target: "definitionPreview", params: { xml: body.bpmn } },
+          window.location.origin,
+        );
+        setStatus("\u2713 Opening the generated DI in the process explorer…", "ok");
+      } else {
+        setStatus(body && body.error ? body.error : "Could not compile the DI for this proposal.", "err");
+      }
+    } catch (err) {
+      setStatus(err && err.message ? err.message : "DI preview request failed.", "err");
+    } finally {
+      busy(false);
+    }
+  }
+  outputEl.addEventListener("click", (ev) => {
+    const btn = ev.target && ev.target.closest ? ev.target.closest("[data-preview-di]") : null;
+    if (!btn) return;
+    ev.preventDefault();
+    doPreviewDi(btn.getAttribute("data-preview-di"));
+  });
+
   return () => {
     root.innerHTML = "";
   };

package/test/delivery-graphs-embed.test.ts

@@ -41,6 +41,17 @@ test("#441: mount.js wires the preview+stage door", () => {
   assert(previewUrl.endsWith("actions/delivery-graph/preview"), `previewUrl default "${previewUrl}" must hit the previewDeliveryGraph door`);
 });
 
+test("DI preview: mount.js wires the proposal-bpmn door (base-relative) and hands the XML to the host explorer", () => {
+  const url = defaultUrl("proposalBpmnUrl");
+  assert(url.endsWith("actions/delivery-graph/proposal-bpmn"), `proposalBpmnUrl default "${url}" must hit the previewProposalBpmn door`);
+  assert(!url.startsWith("/"), `default proposalBpmnUrl "${url}" must be base-relative (App-View #279 resolution class)`);
+  // The staged banner exposes a Preview-DI affordance, and clicking it hands the compiled XML to the
+  // host console over the nano-navigate bridge with the definitionPreview target (never a dispatch).
+  assert(/data-preview-di=/.test(MOUNT_JS), "mount.js must render a Preview-DI affordance carrying the proposal digest");
+  assert(/target:\s*"definitionPreview"/.test(MOUNT_JS), "mount.js must post nano-navigate to the definitionPreview target");
+  assert(/params:\s*\{\s*xml:/.test(MOUNT_JS), "mount.js must carry the compiled BPMN xml in the bridge message");
+});
+
 // The #279 App-View resolution class: a default endpoint must be BASE-RELATIVE (no leading slash) so
 // it resolves under the console app-view base, not the console origin root (which 404s the door).
 test("#441/#279: default previewUrl is base-relative (no leading slash)", () => {