@bpmnkit/cli 0.0.28 → 0.0.30

package/dist/commands/generate.js

@@ -0,0 +1,679 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { Bpmn, compactify, expand } from "@bpmnkit/core";
+// ── JSON schema reference ─────────────────────────────────────────────────────
+const SCHEMA_HELP = `CompactDiagram JSON schema — for --definition and stdin input
+==============================================================
+
+TOP-LEVEL
+  { "id": "Definitions_<unique>", "processes": [CompactProcess] }
+
+CompactProcess
+  { "id": "proc-id", "name"?: "Human Name",
+    "elements": [CompactElement], "flows": [CompactFlow] }
+
+CompactElement — all fields except id+type are optional
+  {
+    "id":             unique element ID,
+    "type":           BpmnElementType (see below),
+    "name":           display label,
+
+    serviceTask/sendTask:
+    "jobType":        Zeebe job type string (e.g. "my-worker"),
+    "taskHeaders":    { key: value } — Zeebe task headers,
+    "resultVariable": variable to store the response in,
+
+    callActivity:
+    "calledProcess":  process ID of the called process,
+
+    userTask:
+    "formId":         Camunda form ID,
+
+    businessRuleTask:
+    "decisionId":     DMN decision ID,
+    "resultVariable": variable to store decision result,
+
+    events (startEvent, endEvent, boundaryEvent, intermediateCatchEvent, etc.):
+    "eventType":      timer | message | signal | error | escalation
+                      | terminate | cancel | conditional | link | compensate,
+
+    boundaryEvent:
+    "attachedTo":     ID of the host task,
+    "interrupting":   false for non-interrupting (default: true),
+
+    subProcess/eventSubProcess/transaction:
+    "children":       { "elements": [...], "flows": [...] }
+  }
+
+CompactFlow
+  {
+    "id":        unique flow ID,
+    "from":      source element ID,
+    "to":        target element ID,
+    "name"?:     flow label,
+    "condition"?: FEEL condition expression (e.g. "= status = \\"approved\\"")
+  }
+
+ELEMENT TYPES
+  Tasks:    serviceTask  userTask  scriptTask  businessRuleTask
+            callActivity  sendTask  receiveTask  manualTask  task
+  Events:   startEvent  endEvent  intermediateCatchEvent  intermediateThrowEvent
+            boundaryEvent
+  Gateways: exclusiveGateway  parallelGateway  inclusiveGateway
+            eventBasedGateway  complexGateway
+  Containers: subProcess  adHocSubProcess  eventSubProcess  transaction
+
+HTTP CONNECTOR (serviceTask)
+  { "type": "serviceTask", "jobType": "io.camunda:http-json:1",
+    "taskHeaders": { "url": "https://...", "method": "POST" },
+    "resultVariable": "response" }
+
+PATCH FORMAT (for --patch and stdin when --input is set)
+  Adds elements and flows to an existing process. IDs must not collide.
+  {
+    "elements": [CompactElement, ...],  // new elements to add
+    "flows":    [CompactFlow, ...]      // new flows to add (can reference existing IDs)
+  }
+
+  Example — add a rejection path to an existing gateway named "gw":
+  {
+    "elements": [
+      { "id": "rejected",  "type": "serviceTask", "name": "Notify Rejection", "jobType": "notify" },
+      { "id": "end-reject","type": "endEvent",     "name": "Rejected" }
+    ],
+    "flows": [
+      { "id": "f-rej1", "from": "gw",       "to": "rejected",  "condition": "= not approved", "name": "No" },
+      { "id": "f-rej2", "from": "rejected",  "to": "end-reject" }
+    ]
+  }
+
+FULL EXAMPLE — order approval
+  {
+    "id": "Definitions_order",
+    "processes": [{
+      "id": "order-approval",
+      "name": "Order Approval",
+      "elements": [
+        { "id": "start",     "type": "startEvent",      "name": "Order Received" },
+        { "id": "validate",  "type": "serviceTask",     "name": "Validate",      "jobType": "validate-order" },
+        { "id": "gw",        "type": "exclusiveGateway","name": "Valid?" },
+        { "id": "review",    "type": "userTask",        "name": "Manual Review", "formId": "review-form" },
+        { "id": "process",   "type": "serviceTask",     "name": "Process Order", "jobType": "process-order" },
+        { "id": "end-ok",    "type": "endEvent",        "name": "Processed" },
+        { "id": "end-rej",   "type": "endEvent",        "name": "Rejected" },
+        { "id": "err",       "type": "boundaryEvent",   "attachedTo": "validate", "eventType": "error" },
+        { "id": "end-err",   "type": "endEvent",        "name": "Validation Error", "eventType": "error" }
+      ],
+      "flows": [
+        { "id": "f1", "from": "start",    "to": "validate" },
+        { "id": "f2", "from": "validate", "to": "gw" },
+        { "id": "f3", "from": "gw",       "to": "review",  "condition": "= not valid", "name": "Invalid" },
+        { "id": "f4", "from": "gw",       "to": "process", "condition": "= valid",     "name": "Valid" },
+        { "id": "f5", "from": "review",   "to": "end-rej", "name": "Rejected" },
+        { "id": "f6", "from": "review",   "to": "process", "name": "Approved" },
+        { "id": "f7", "from": "process",  "to": "end-ok" },
+        { "id": "f8", "from": "err",      "to": "end-err" }
+      ]
+    }]
+  }`;
+const TEMPLATES = {
+    empty: (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "New Process",
+                elements: [{ id: "start", type: "startEvent", name: "Start" }],
+                flows: [],
+            },
+        ],
+    }),
+    minimal: (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "New Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    {
+                        id: "task1",
+                        type: "serviceTask",
+                        name: name ? `${name} Task` : "Process Request",
+                        jobType: "my-worker",
+                    },
+                    { id: "end", type: "endEvent", name: "End" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "task1" },
+                    { id: "f2", from: "task1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "user-task": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Human Task Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    { id: "ut1", type: "userTask", name: name ?? "Review", formId: "my-form" },
+                    { id: "end", type: "endEvent", name: "Done" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "ut1" },
+                    { id: "f2", from: "ut1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "call-activity": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Orchestration Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    {
+                        id: "ca1",
+                        type: "callActivity",
+                        name: name ?? "Run Sub-Process",
+                        calledProcess: "child-process",
+                    },
+                    { id: "end", type: "endEvent", name: "Done" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "ca1" },
+                    { id: "f2", from: "ca1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "business-rule": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Decision Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    {
+                        id: "brt1",
+                        type: "businessRuleTask",
+                        name: name ?? "Evaluate Decision",
+                        decisionId: "my-decision",
+                        resultVariable: "decisionResult",
+                    },
+                    { id: "end", type: "endEvent", name: "Done" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "brt1" },
+                    { id: "f2", from: "brt1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    approval: (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Approval Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Request Received" },
+                    { id: "review", type: "userTask", name: "Review Request", formId: "review-form" },
+                    { id: "gw", type: "exclusiveGateway", name: "Approved?" },
+                    {
+                        id: "process",
+                        type: "serviceTask",
+                        name: "Process Approval",
+                        jobType: "process-approval",
+                    },
+                    { id: "end-ok", type: "endEvent", name: "Approved" },
+                    { id: "end-rej", type: "endEvent", name: "Rejected" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "review" },
+                    { id: "f2", from: "review", to: "gw" },
+                    { id: "f3", from: "gw", to: "process", condition: "= approved", name: "Yes" },
+                    { id: "f4", from: "gw", to: "end-rej", condition: "= not approved", name: "No" },
+                    { id: "f5", from: "process", to: "end-ok" },
+                ],
+            },
+        ],
+    }),
+    parallel: (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Parallel Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    { id: "fork", type: "parallelGateway", name: "Fork" },
+                    { id: "task1", type: "serviceTask", name: "Task A", jobType: "task-a" },
+                    { id: "task2", type: "serviceTask", name: "Task B", jobType: "task-b" },
+                    { id: "join", type: "parallelGateway", name: "Join" },
+                    { id: "end", type: "endEvent", name: "End" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "fork" },
+                    { id: "f2", from: "fork", to: "task1" },
+                    { id: "f3", from: "fork", to: "task2" },
+                    { id: "f4", from: "task1", to: "join" },
+                    { id: "f5", from: "task2", to: "join" },
+                    { id: "f6", from: "join", to: "end" },
+                ],
+            },
+        ],
+    }),
+    inclusive: (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Inclusive Gateway Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    { id: "split", type: "inclusiveGateway", name: "Which?" },
+                    { id: "task1", type: "serviceTask", name: "Option A", jobType: "option-a" },
+                    { id: "task2", type: "serviceTask", name: "Option B", jobType: "option-b" },
+                    { id: "merge", type: "inclusiveGateway", name: "Merge" },
+                    { id: "end", type: "endEvent", name: "End" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "split" },
+                    { id: "f2", from: "split", to: "task1", condition: "= needsA", name: "A" },
+                    { id: "f3", from: "split", to: "task2", condition: "= needsB", name: "B" },
+                    { id: "f4", from: "task1", to: "merge" },
+                    { id: "f5", from: "task2", to: "merge" },
+                    { id: "f6", from: "merge", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "timer-start": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Scheduled Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Timer", eventType: "timer" },
+                    {
+                        id: "task1",
+                        type: "serviceTask",
+                        name: name ?? "Scheduled Job",
+                        jobType: "scheduled-worker",
+                    },
+                    { id: "end", type: "endEvent", name: "Done" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "task1" },
+                    { id: "f2", from: "task1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "message-start": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Message-Triggered Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Message Received", eventType: "message" },
+                    {
+                        id: "task1",
+                        type: "serviceTask",
+                        name: name ?? "Handle Message",
+                        jobType: "message-handler",
+                    },
+                    { id: "end", type: "endEvent", name: "Done" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "task1" },
+                    { id: "f2", from: "task1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "error-boundary": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Error Handling Process",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    { id: "task1", type: "serviceTask", name: name ?? "Risky Task", jobType: "risky-worker" },
+                    {
+                        id: "err",
+                        type: "boundaryEvent",
+                        attachedTo: "task1",
+                        eventType: "error",
+                        name: "Error",
+                    },
+                    { id: "end-ok", type: "endEvent", name: "Success" },
+                    { id: "end-err", type: "endEvent", name: "Failed", eventType: "error" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "task1" },
+                    { id: "f2", from: "task1", to: "end-ok" },
+                    { id: "f3", from: "err", to: "end-err" },
+                ],
+            },
+        ],
+    }),
+    subprocess: (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Sub-Process Demo",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    {
+                        id: "sp1",
+                        type: "subProcess",
+                        name: name ?? "Sub-Process",
+                        children: {
+                            elements: [
+                                { id: "sp_start", type: "startEvent", name: "Begin" },
+                                { id: "sp_task", type: "serviceTask", name: "Inner Task", jobType: "inner-worker" },
+                                { id: "sp_end", type: "endEvent", name: "Finish" },
+                            ],
+                            flows: [
+                                { id: "sf1", from: "sp_start", to: "sp_task" },
+                                { id: "sf2", from: "sp_task", to: "sp_end" },
+                            ],
+                        },
+                    },
+                    { id: "end", type: "endEvent", name: "End" },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "sp1" },
+                    { id: "f2", from: "sp1", to: "end" },
+                ],
+            },
+        ],
+    }),
+    "event-subprocess": (id, name) => ({
+        id: `Definitions_${id}`,
+        processes: [
+            {
+                id,
+                name: name ?? "Process with Error Handler",
+                elements: [
+                    { id: "start", type: "startEvent", name: "Start" },
+                    { id: "task1", type: "serviceTask", name: name ?? "Main Task", jobType: "main-worker" },
+                    { id: "end", type: "endEvent", name: "End" },
+                    {
+                        id: "evtsp",
+                        type: "eventSubProcess",
+                        name: "Error Handler",
+                        children: {
+                            elements: [
+                                {
+                                    id: "evtsp_start",
+                                    type: "startEvent",
+                                    name: "Error",
+                                    eventType: "error",
+                                    interrupting: false,
+                                },
+                                {
+                                    id: "evtsp_task",
+                                    type: "serviceTask",
+                                    name: "Compensate",
+                                    jobType: "compensate-worker",
+                                },
+                                { id: "evtsp_end", type: "endEvent", name: "Handled" },
+                            ],
+                            flows: [
+                                { id: "sf1", from: "evtsp_start", to: "evtsp_task" },
+                                { id: "sf2", from: "evtsp_task", to: "evtsp_end" },
+                            ],
+                        },
+                    },
+                ],
+                flows: [
+                    { id: "f1", from: "start", to: "task1" },
+                    { id: "f2", from: "task1", to: "end" },
+                ],
+            },
+        ],
+    }),
+};
+const TEMPLATE_NAMES = Object.keys(TEMPLATES).sort();
+// ── Stdin reader ──────────────────────────────────────────────────────────────
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8").trim();
+}
+// ── Command ───────────────────────────────────────────────────────────────────
+const generateBpmnCmd = {
+    name: "bpmn",
+    description: "Generate a BPMN file from parameters, a template, or a CompactDiagram JSON definition",
+    args: [],
+    flags: [
+        {
+            name: "process-id",
+            short: "i",
+            description: "Process ID (used in templates)",
+            type: "string",
+        },
+        {
+            name: "name",
+            short: "n",
+            description: "Process display name (used in templates)",
+            type: "string",
+        },
+        {
+            name: "output",
+            short: "o",
+            description: "Output file path. Default: <process-id>.bpmn. Use - for stdout.",
+            type: "string",
+        },
+        {
+            name: "template",
+            description: `Template name. Options: ${TEMPLATE_NAMES.join(", ")}`,
+            type: "string",
+            default: "minimal",
+            enum: TEMPLATE_NAMES,
+        },
+        {
+            name: "definition",
+            short: "d",
+            description: "CompactDiagram JSON string (overrides --template). See --help-schema.",
+            type: "string",
+        },
+        {
+            name: "help-schema",
+            description: "Print the CompactDiagram JSON schema and exit",
+            type: "boolean",
+        },
+        {
+            name: "input",
+            short: "f",
+            description: "Existing .bpmn file to load and modify",
+            type: "string",
+        },
+        {
+            name: "patch",
+            description: 'JSON patch to apply to --input: {"elements":[...],"flows":[...]}. See --help-schema.',
+            type: "string",
+        },
+        {
+            name: "dump-compact",
+            description: "Print the CompactDiagram JSON of --input and exit (for AI inspection of existing files)",
+            type: "boolean",
+        },
+    ],
+    examples: [
+        {
+            description: "Minimal service-task process",
+            command: "casen generate bpmn --process-id order --name 'Order Processing'",
+        },
+        {
+            description: "Approval workflow template",
+            command: "casen generate bpmn --template approval --process-id approve",
+        },
+        {
+            description: "Timer-triggered scheduled job",
+            command: "casen generate bpmn --template timer-start --process-id nightly-sync",
+        },
+        {
+            description: "Parallel branch pattern",
+            command: "casen generate bpmn --template parallel --process-id enrich --name Enrichment",
+        },
+        {
+            description: "Error boundary with error end event",
+            command: "casen generate bpmn --template error-boundary --process-id resilient",
+        },
+        {
+            description: "Full custom definition (AI/scripting path)",
+            command: 'casen generate bpmn --definition \'{"id":"Defs","processes":[{"id":"p","elements":[...],"flows":[...]}]}\'',
+        },
+        {
+            description: "Pipe CompactDiagram JSON from AI output",
+            command: "echo '{...}' | casen generate bpmn --output my-process.bpmn",
+        },
+        {
+            description: "Print full JSON schema reference",
+            command: "casen generate bpmn --help-schema",
+        },
+        {
+            description: "Inspect an existing file as compact JSON (AI planning step)",
+            command: "casen generate bpmn --input existing.bpmn --dump-compact",
+        },
+        {
+            description: "Add a new gateway path to an existing file",
+            command: 'casen generate bpmn --input order.bpmn --patch \'{"elements":[{"id":"notify","type":"serviceTask","name":"Notify","jobType":"notify-worker"},{"id":"end2","type":"endEvent","name":"Notified"}],"flows":[{"id":"fn1","from":"gw","to":"notify","condition":"= urgent"},{"id":"fn2","from":"notify","to":"end2"}]}\'',
+        },
+        {
+            description: "Pipe a patch from AI output",
+            command: 'echo \'{"elements":[...],"flows":[...]}\' | casen generate bpmn --input order.bpmn',
+        },
+        {
+            description: "Re-apply auto-layout to an existing file",
+            command: "casen generate bpmn --input messy.bpmn --output clean.bpmn",
+        },
+    ],
+    async run(ctx) {
+        // --help-schema: print schema and exit
+        if (ctx.flags["help-schema"]) {
+            process.stdout.write(`${SCHEMA_HELP}\n`);
+            return;
+        }
+        const processId = ctx.flags["process-id"]?.trim() || "process";
+        const name = ctx.flags.name?.trim();
+        const outputFlag = ctx.flags.output;
+        const defFlag = ctx.flags.definition;
+        const inputFile = ctx.flags.input;
+        const patchFlag = ctx.flags.patch;
+        // ── Modify-existing mode (--input) ─────────────────────────────────────
+        if (inputFile) {
+            const xml = await readFile(inputFile, "utf-8");
+            const defs = Bpmn.parse(xml);
+            const compact = compactify(defs);
+            // --dump-compact: print JSON for AI inspection and exit
+            if (ctx.flags["dump-compact"]) {
+                process.stdout.write(`${JSON.stringify(compact, null, 2)}\n`);
+                return;
+            }
+            // Resolve patch from --patch flag or stdin
+            let patch = null;
+            if (patchFlag) {
+                try {
+                    patch = JSON.parse(patchFlag);
+                }
+                catch {
+                    throw new Error("--patch is not valid JSON. Run --help-schema to see the format.");
+                }
+            }
+            else if (!process.stdin.isTTY) {
+                const raw = await readStdin();
+                if (raw) {
+                    try {
+                        patch = JSON.parse(raw);
+                    }
+                    catch {
+                        throw new Error("stdin is not valid patch JSON. Expected {elements:[...],flows:[...]}. Run --help-schema.");
+                    }
+                }
+            }
+            // Apply patch to first process (covers all single-process cases)
+            if (patch) {
+                const proc = compact.processes[0];
+                if (!proc)
+                    throw new Error("Input BPMN has no processes");
+                if (patch.elements?.length)
+                    proc.elements.push(...patch.elements);
+                if (patch.flows?.length)
+                    proc.flows.push(...patch.flows);
+            }
+            const patched = Bpmn.export(expand(compact));
+            if (outputFlag === "-") {
+                process.stdout.write(patched);
+                return;
+            }
+            const outputPath = typeof outputFlag === "string" && outputFlag.length > 0 ? outputFlag : inputFile;
+            await writeFile(outputPath, patched, "utf-8");
+            ctx.output.ok(patch ? `Patched and written to ${outputPath}` : `Re-laid-out and written to ${outputPath}`);
+            return;
+        }
+        // ── Generate mode (template / definition / stdin) ──────────────────────
+        let compact = null;
+        if (defFlag) {
+            try {
+                compact = JSON.parse(defFlag);
+            }
+            catch {
+                throw new Error("--definition is not valid JSON. Run --help-schema to see the format.");
+            }
+        }
+        else if (!process.stdin.isTTY) {
+            const raw = await readStdin();
+            if (raw) {
+                try {
+                    compact = JSON.parse(raw);
+                }
+                catch {
+                    throw new Error("stdin is not valid CompactDiagram JSON. Run --help-schema to see the format.");
+                }
+            }
+        }
+        let xml;
+        if (compact) {
+            xml = Bpmn.export(expand(compact));
+        }
+        else {
+            const templateName = ctx.flags.template ?? "minimal";
+            const templateFn = TEMPLATES[templateName];
+            if (!templateFn) {
+                throw new Error(`Unknown template "${templateName}". Available: ${TEMPLATE_NAMES.join(", ")}`);
+            }
+            xml = Bpmn.export(expand(templateFn(processId, name)));
+        }
+        if (outputFlag === "-") {
+            process.stdout.write(xml);
+            return;
+        }
+        const effectiveId = compact?.processes[0]?.id ?? ctx.flags["process-id"] ?? "process";
+        const outputPath = typeof outputFlag === "string" && outputFlag.length > 0 ? outputFlag : `${effectiveId}.bpmn`;
+        await writeFile(outputPath, xml, "utf-8");
+        ctx.output.ok(`BPMN written to ${outputPath}`);
+    },
+};
+export const generateGroup = {
+    name: "generate",
+    aliases: ["gen"],
+    description: "Generate BPMN, DMN, and form files from parameters",
+    commands: [generateBpmnCmd],
+};
+//# sourceMappingURL=generate.js.map

package/dist/commands/index.js

@@ -4,6 +4,7 @@ import { askGroup } from "./ask.js";
 import { getDmnReqsXmlCmd, getDmnXmlCmd, getStartFormCmd, getUserTaskFormCmd, getXmlCmd, renderBpmnCmd, } from "./bpmn.js";
 import { completionGroup } from "./completion.js";
 import { connectorGroup } from "./connector.js";
+import { generateGroup } from "./generate.js";
 import { lintGroup } from "./lint.js";
 import { pluginGroup } from "./plugin.js";
 import { profileGroup } from "./profile.js";
@@ -14,6 +15,7 @@ import { settingsGroup } from "./settings.js";
 import { skillsGroup } from "./skills.js";
 import { storyGroup } from "./story.js";
 import { testGroup } from "./test.js";
+import { viewGroup } from "./view.js";
 import { workerStartCmd } from "./worker-start.js";
 import { workerCmd } from "./worker.js";
 // Inject custom commands into generated groups without modifying generated files.
@@ -55,6 +57,7 @@ const workerGroup = {
 /** Pinned groups shown above the separator in the main TUI menu. */
 export const pinnedGroups = [
     askGroup,
+    generateGroup,
     lintGroup,
     proxyGroup,
     reebeGroup,
@@ -62,6 +65,7 @@ export const pinnedGroups = [
     storyGroup,
     settingsGroup,
     testGroup,
+    viewGroup,
     workerGroup,
 ];
 /** API command groups — shown below the plugin section in the main TUI menu. */

package/dist/commands/view.js

@@ -0,0 +1,373 @@
+import { spawn } from "node:child_process";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { basename, extname, join } from "node:path";
+import { renderDmnAscii, renderFormAscii } from "@bpmnkit/ascii";
+import { Bpmn, exportSvg } from "@bpmnkit/core";
+// ── Utilities ─────────────────────────────────────────────────────────────────
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).unref();
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** Expand paths: directories are scanned (top-level) for matching extensions. */
+async function resolvePaths(paths, extensions) {
+    const result = [];
+    for (const p of paths) {
+        const s = await stat(p).catch(() => null);
+        if (!s)
+            throw new Error(`Path not found: ${p}`);
+        if (s.isDirectory()) {
+            const entries = await readdir(p, { withFileTypes: true });
+            const matched = entries
+                .filter((e) => e.isFile() && extensions.includes(extname(e.name).toLowerCase()))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((e) => join(p, e.name));
+            if (matched.length === 0) {
+                throw new Error(`No ${extensions.join("/")} files found in directory: ${p}`);
+            }
+            result.push(...matched);
+        }
+        else {
+            result.push(p);
+        }
+    }
+    return result;
+}
+// ── Panel builders ────────────────────────────────────────────────────────────
+async function buildBpmnPanel(file, theme) {
+    const xml = await readFile(file, "utf-8");
+    const defs = Bpmn.parse(xml);
+    return { label: basename(file), type: "bpmn", content: exportSvg(defs, { theme }) };
+}
+async function buildDmnPanel(file) {
+    const xml = await readFile(file, "utf-8");
+    return { label: basename(file), type: "dmn", content: renderDmnAscii(xml) };
+}
+async function buildFormPanel(file) {
+    const json = await readFile(file, "utf-8");
+    return { label: basename(file), type: "form", content: renderFormAscii(json) };
+}
+async function panelFromFile(file, theme) {
+    const ext = extname(file).toLowerCase();
+    if (ext === ".bpmn")
+        return buildBpmnPanel(file, theme);
+    if (ext === ".dmn")
+        return buildDmnPanel(file);
+    if (ext === ".form")
+        return buildFormPanel(file);
+    throw new Error(`Unsupported file extension: ${file}. Use .bpmn, .dmn, or .form`);
+}
+// ── HTML builder ──────────────────────────────────────────────────────────────
+function buildHtml(panels, theme) {
+    const tabs = panels
+        .map((p, i) => `<button class="tab${i === 0 ? " active" : ""}" data-idx="${i}" data-type="${p.type}">${escapeHtml(p.label)}</button>`)
+        .join("\n    ");
+    const panelHtml = panels
+        .map((p, i) => {
+        const cls = `panel${i === 0 ? " active" : ""}`;
+        if (p.type === "bpmn") {
+            return `<div class="${cls}" data-idx="${i}" data-type="bpmn">${p.content}</div>`;
+        }
+        return `<div class="${cls}" data-idx="${i}" data-type="${p.type}"><pre>${escapeHtml(p.content)}</pre></div>`;
+    })
+        .join("\n  ");
+    return `<!DOCTYPE html>
+<html lang="en" data-theme="${theme}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>BPMN Kit Viewer</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0 }
+    :root {
+      --bg: #f4f4f8; --surface: #ffffff; --border: #d0d0e8;
+      --fg: #1a1a2e; --fg-muted: #6666a0; --accent: #1a56db;
+      --mono: ui-monospace, "Cascadia Code", "JetBrains Mono", monospace;
+    }
+    [data-theme="dark"] {
+      --bg: #0d0d16; --surface: #161626; --border: #2a2a42;
+      --fg: #cdd6f4; --fg-muted: #8888a8; --accent: #6b9df7;
+    }
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: var(--bg);
+      color: var(--fg);
+      height: 100vh;
+      display: flex;
+      flex-direction: column;
+    }
+    header {
+      background: var(--surface);
+      border-bottom: 1px solid var(--border);
+      padding: 0 16px;
+      display: flex;
+      align-items: center;
+      gap: 2px;
+      overflow-x: auto;
+      flex-shrink: 0;
+      height: 44px;
+    }
+    .brand {
+      font-size: 11px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--fg-muted);
+      margin-right: 12px;
+      white-space: nowrap;
+    }
+    .tab {
+      padding: 6px 14px;
+      border: none;
+      border-bottom: 2px solid transparent;
+      background: none;
+      color: var(--fg-muted);
+      font: inherit;
+      font-size: 13px;
+      cursor: pointer;
+      border-radius: 4px 4px 0 0;
+      white-space: nowrap;
+      transition: color 0.1s;
+    }
+    .tab.active { color: var(--accent); border-bottom-color: var(--accent); font-weight: 500; }
+    .tab:hover:not(.active) { color: var(--fg); }
+    .tab-type {
+      font-size: 9px;
+      font-weight: 700;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      opacity: 0.6;
+      margin-left: 5px;
+      vertical-align: middle;
+    }
+    main {
+      flex: 1;
+      overflow: auto;
+      padding: 24px;
+      display: flex;
+      justify-content: center;
+      align-items: flex-start;
+    }
+    .panel { display: none; width: 100%; }
+    .panel.active { display: block; }
+    .panel[data-type="bpmn"] svg {
+      max-width: 100%;
+      height: auto;
+      border-radius: 8px;
+      box-shadow: 0 2px 16px rgba(0,0,0,0.1);
+    }
+    .panel[data-type="dmn"] pre,
+    .panel[data-type="form"] pre {
+      font-family: var(--mono);
+      font-size: 13px;
+      line-height: 1.5;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 20px 24px;
+      overflow-x: auto;
+      white-space: pre;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+    }
+    footer {
+      background: var(--surface);
+      border-top: 1px solid var(--border);
+      padding: 6px 16px;
+      font-size: 11px;
+      color: var(--fg-muted);
+      flex-shrink: 0;
+    }
+    kbd {
+      background: var(--border);
+      border-radius: 3px;
+      padding: 1px 4px;
+      font-family: inherit;
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <span class="brand">BPMN Kit</span>
+    ${tabs}
+  </header>
+  <main>
+  ${panelHtml}
+  </main>
+  <footer>
+    Use <kbd>Ctrl+Scroll</kbd> or browser zoom to zoom &mdash;
+    Press <kbd>Ctrl+C</kbd> in terminal to stop the server
+  </footer>
+  <script>
+    const tabs = document.querySelectorAll('.tab')
+    const panels = document.querySelectorAll('.panel')
+    tabs.forEach(tab => {
+      tab.addEventListener('click', () => {
+        const idx = tab.dataset.idx
+        tabs.forEach(t => t.classList.toggle('active', t.dataset.idx === idx))
+        panels.forEach(p => p.classList.toggle('active', p.dataset.idx === idx))
+      })
+    })
+  </script>
+</body>
+</html>`;
+}
+// ── Server ────────────────────────────────────────────────────────────────────
+async function serve(panels, port, theme, noOpen, ctx) {
+    const html = buildHtml(panels, theme);
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(port, "127.0.0.1", () => resolve());
+        server.on("error", reject);
+    });
+    const url = `http://localhost:${port}`;
+    ctx.output.info(`Serving ${panels.length} file${panels.length === 1 ? "" : "s"} at ${url}`);
+    if (!noOpen)
+        openBrowser(url);
+    ctx.output.info("Press Ctrl+C to stop");
+    await new Promise((resolve) => {
+        process.once("SIGINT", resolve);
+        process.once("SIGTERM", resolve);
+    });
+    server.close();
+}
+// ── Shared flags ──────────────────────────────────────────────────────────────
+const PORT_FLAG = {
+    name: "port",
+    description: "Port for the local server (default: 3044)",
+    type: "number",
+    default: 3044,
+};
+const THEME_FLAG = {
+    name: "theme",
+    description: "Color theme: light (default) or dark",
+    type: "string",
+    default: "light",
+    enum: ["light", "dark"],
+};
+const NO_OPEN_FLAG = {
+    name: "no-open",
+    description: "Do not open the browser automatically",
+    type: "boolean",
+};
+// ── Commands ──────────────────────────────────────────────────────────────────
+const viewBpmnCmd = {
+    name: "bpmn",
+    description: "View BPMN files or a folder of .bpmn files in the browser",
+    args: [
+        { name: "path", description: "File(s) or folder(s) containing .bpmn files", required: true },
+    ],
+    flags: [PORT_FLAG, THEME_FLAG, NO_OPEN_FLAG],
+    examples: [
+        { description: "View a single file", command: "casen view bpmn process.bpmn" },
+        { description: "View all files in a folder", command: "casen view bpmn ./processes/" },
+        { description: "View multiple files", command: "casen view bpmn order.bpmn payment.bpmn" },
+        {
+            description: "Dark theme on custom port",
+            command: "casen view bpmn process.bpmn --theme dark --port 8080",
+        },
+    ],
+    async run(ctx) {
+        if (ctx.positional.length === 0)
+            throw new Error("Provide at least one file or folder path");
+        const port = ctx.flags.port ?? 3044;
+        const theme = ctx.flags.theme === "dark" ? "dark" : "light";
+        const files = await resolvePaths(ctx.positional, [".bpmn"]);
+        const panels = await Promise.all(files.map((f) => buildBpmnPanel(f, theme)));
+        await serve(panels, port, theme, ctx.flags["no-open"] === true, ctx);
+    },
+};
+const viewDmnCmd = {
+    name: "dmn",
+    description: "View DMN files or a folder of .dmn files in the browser",
+    args: [
+        { name: "path", description: "File(s) or folder(s) containing .dmn files", required: true },
+    ],
+    flags: [PORT_FLAG, THEME_FLAG, NO_OPEN_FLAG],
+    examples: [
+        { description: "View a single DMN file", command: "casen view dmn decision.dmn" },
+        { description: "View all DMN files in a folder", command: "casen view dmn ./decisions/" },
+    ],
+    async run(ctx) {
+        if (ctx.positional.length === 0)
+            throw new Error("Provide at least one file or folder path");
+        const port = ctx.flags.port ?? 3044;
+        const theme = ctx.flags.theme === "dark" ? "dark" : "light";
+        const files = await resolvePaths(ctx.positional, [".dmn"]);
+        const panels = await Promise.all(files.map((f) => buildDmnPanel(f)));
+        await serve(panels, port, theme, ctx.flags["no-open"] === true, ctx);
+    },
+};
+const viewFormCmd = {
+    name: "form",
+    description: "View Camunda form files or a folder of .form files in the browser",
+    args: [
+        { name: "path", description: "File(s) or folder(s) containing .form files", required: true },
+    ],
+    flags: [PORT_FLAG, THEME_FLAG, NO_OPEN_FLAG],
+    examples: [
+        { description: "View a single form file", command: "casen view form my-form.form" },
+        { description: "View all forms in a folder", command: "casen view form ./forms/" },
+    ],
+    async run(ctx) {
+        if (ctx.positional.length === 0)
+            throw new Error("Provide at least one file or folder path");
+        const port = ctx.flags.port ?? 3044;
+        const theme = ctx.flags.theme === "dark" ? "dark" : "light";
+        const files = await resolvePaths(ctx.positional, [".form"]);
+        const panels = await Promise.all(files.map((f) => buildFormPanel(f)));
+        await serve(panels, port, theme, ctx.flags["no-open"] === true, ctx);
+    },
+};
+const viewOpenCmd = {
+    name: "open",
+    description: "View any mix of .bpmn, .dmn, and .form files or folders in the browser",
+    args: [
+        {
+            name: "path",
+            description: "File(s) or folder(s) — .bpmn, .dmn, and .form auto-detected",
+            required: true,
+        },
+    ],
+    flags: [PORT_FLAG, THEME_FLAG, NO_OPEN_FLAG],
+    examples: [
+        {
+            description: "Open any supported file",
+            command: "casen view open process.bpmn decision.dmn",
+        },
+        { description: "Open a folder (all supported types)", command: "casen view open ./project/" },
+        {
+            description: "Mix files and folders",
+            command: "casen view open ./processes/ extra.dmn review.form",
+        },
+    ],
+    async run(ctx) {
+        if (ctx.positional.length === 0)
+            throw new Error("Provide at least one file or folder path");
+        const port = ctx.flags.port ?? 3044;
+        const theme = ctx.flags.theme === "dark" ? "dark" : "light";
+        const files = await resolvePaths(ctx.positional, [".bpmn", ".dmn", ".form"]);
+        const panels = await Promise.all(files.map((f) => panelFromFile(f, theme)));
+        await serve(panels, port, theme, ctx.flags["no-open"] === true, ctx);
+    },
+};
+// ── Group ─────────────────────────────────────────────────────────────────────
+export const viewGroup = {
+    name: "view",
+    description: "View BPMN, DMN, and form files in the browser via a local server",
+    commands: [viewOpenCmd, viewBpmnCmd, viewDmnCmd, viewFormCmd],
+};
+//# sourceMappingURL=view.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/cli",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "Command-line interface for Camunda 8 — deploy, manage, and monitor processes from the terminal",
   "type": "module",
   "bin": {
@@ -17,12 +17,12 @@
   },
   "dependencies": {
     "@bpmnkit/api": "0.0.18",
+    "@bpmnkit/ascii": "0.0.23",
     "@bpmnkit/connector-gen": "0.0.13",
-    "@bpmnkit/core": "0.0.22",
-    "@bpmnkit/ascii": "0.0.22",
-    "@bpmnkit/engine": "0.1.22",
+    "@bpmnkit/core": "0.0.23",
+    "@bpmnkit/engine": "0.1.23",
     "@bpmnkit/profiles": "0.0.16",
-    "@bpmnkit/proxy": "0.0.25"
+    "@bpmnkit/proxy": "0.0.26"
   },
   "publishConfig": {
     "access": "public"