@bpmnkit/cli 0.0.36 → 0.1.0

package/dist/commands/synth.js

@@ -0,0 +1,103 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { applyConnectorTemplate } from "@bpmnkit/connectors";
+import { Bpmn, compilePlan, mergePlan, slugify, uniqueId } from "@bpmnkit/core";
+async function readPlan(path) {
+    const text = await readFile(resolve(path), "utf-8");
+    return JSON.parse(text);
+}
+/** Convert plan-embedded test scenarios to the `.bpmn.tests.json` shape consumed by `casen test`. */
+export function toScenarioSidecar(tests) {
+    const taken = new Set();
+    return tests.map((t) => {
+        const id = uniqueId(slugify(t.name), taken);
+        const mocks = Object.fromEntries(Object.entries(t.mocks ?? {}).map(([jobType, mock]) => [
+            jobType,
+            "error" in mock
+                ? {
+                    error: mock.error.message
+                        ? `${mock.error.code}: ${mock.error.message}`
+                        : mock.error.code,
+                }
+                : { outputs: mock.outputs },
+        ]));
+        return { id, name: t.name, inputs: t.inputs, mocks, expect: t.expect };
+    });
+}
+const synthCmd = {
+    name: "synth",
+    description: "Compile a ProcessPlan JSON file into deployable, laid-out BPMN XML",
+    args: [{ name: "plan", description: "Path to the ProcessPlan JSON file", required: true }],
+    flags: [
+        {
+            name: "output",
+            short: "o",
+            description: "Output .bpmn file path (default: <plan>.bpmn)",
+            type: "string",
+        },
+        {
+            name: "merge",
+            description: "Merge into an existing .bpmn file instead of creating a new one",
+            type: "string",
+        },
+        {
+            name: "json",
+            description: "Print the result (problems + xml) as JSON instead of writing a file",
+            type: "boolean",
+        },
+    ],
+    examples: [
+        { description: "Compile a plan to BPMN", command: "casen synth order-process.plan.json" },
+        {
+            description: "Extend an existing process",
+            command: "casen synth delta.plan.json --merge order-process.bpmn",
+        },
+    ],
+    async run(ctx) {
+        const planPath = ctx.positional[0];
+        if (!planPath)
+            throw new Error("Missing required argument: <plan>");
+        const plan = await readPlan(planPath);
+        const mergeTarget = typeof ctx.flags.merge === "string" ? ctx.flags.merge : undefined;
+        const result = mergeTarget
+            ? mergePlan(Bpmn.parse(await readFile(resolve(mergeTarget), "utf-8")), plan, {
+                resolveConnector: applyConnectorTemplate,
+            })
+            : compilePlan(plan, { resolveConnector: applyConnectorTemplate });
+        if (ctx.flags.json) {
+            ctx.output.print(result);
+            if (!result.xml)
+                process.exitCode = 1;
+            return;
+        }
+        if (result.problems.length > 0) {
+            for (const p of result.problems)
+                ctx.output.info(`✖ [${p.path}] ${p.message}`);
+        }
+        if (!result.xml) {
+            throw new Error(`Compilation failed with ${result.problems.length} problem(s) — see above`);
+        }
+        const outputPath = resolve(typeof ctx.flags.output === "string"
+            ? ctx.flags.output
+            : (mergeTarget ?? planPath.replace(/\.json$/, ".bpmn")));
+        await writeFile(outputPath, result.xml, "utf-8");
+        if (plan.tests && plan.tests.length > 0) {
+            const sidecarPath = `${outputPath}.tests.json`;
+            await writeFile(sidecarPath, JSON.stringify(toScenarioSidecar(plan.tests), null, 2), "utf-8");
+            ctx.output.info(`Wrote ${sidecarPath} (${plan.tests.length} scenario(s) — run: casen test ${outputPath})`);
+        }
+        if (result.problems.length > 0) {
+            ctx.output.info(`\nWrote ${outputPath} with ${result.problems.length} problem(s) above.`);
+            process.exitCode = 1;
+        }
+        else {
+            ctx.output.ok(`Wrote ${outputPath}`);
+        }
+    },
+};
+export const synthGroup = {
+    name: "synth",
+    description: "Compile a ProcessPlan into deployable BPMN — the deterministic AI-generation pipeline",
+    commands: [synthCmd],
+};
+//# sourceMappingURL=synth.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/cli",
-  "version": "0.0.36",
+  "version": "0.1.0",
   "description": "Command-line interface for Camunda 8 — deploy, manage, and monitor processes from the terminal",
   "type": "module",
   "bin": {
@@ -16,13 +16,15 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@bpmnkit/api": "0.0.19",
-    "@bpmnkit/ascii": "0.0.29",
-    "@bpmnkit/connector-gen": "0.0.14",
-    "@bpmnkit/core": "0.1.1",
-    "@bpmnkit/engine": "0.1.29",
-    "@bpmnkit/profiles": "0.0.17",
-    "@bpmnkit/proxy": "0.0.32"
+    "@bpmnkit/api": "0.0.20",
+    "@bpmnkit/ascii": "0.0.31",
+    "@bpmnkit/connector-gen": "0.0.15",
+    "@bpmnkit/connectors": "0.0.3",
+    "@bpmnkit/core": "0.2.0",
+    "@bpmnkit/engine": "0.1.31",
+    "@bpmnkit/patterns": "0.0.5",
+    "@bpmnkit/profiles": "0.0.18",
+    "@bpmnkit/proxy": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/aikit.md

@@ -1,267 +1,46 @@
-# BPMNKit AIKit — Tool Reference
+# BPMNKit — Reference
 
-This file is installed to `.claude/aikit.md` by `casen skills install`.
-The skill files (`/design`, `/implement`, etc.) reference it with `@.claude/aikit.md`.
+This file is installed to `.claude/aikit.md` by `casen skills install`. The skill files (`/implement`, `/review`, `/test`, `/deploy`) reference it with `@.claude/aikit.md`.
 
----
-
-## MCP server
-
-All tools are exposed by the `bpmnkit-aikit` MCP server configured in `.claude/mcp.json`.
-Tool names follow the pattern `mcp__bpmnkit-aikit__<tool_name>`.
-
----
-
-## BPMN tools
-
-### `bpmn_create`
-
-Generate a new BPMN process from a natural language description.
-
-- Automatically loads a matching domain pattern for context before calling the AI.
-- Writes the `.bpmn` file to disk.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `description` | yes | Natural language description of the process. Include actors, decision points, and expected outcomes. The richer the description, the better the diagram. |
-| `outputDir` | no | Directory to write the file (default: current working directory). |
-
-**Returns** `{ path: string, patternMatched: string | null }`
-
-**Good description example:**
-> "Invoice approval process with a clerk review step, automatic approval under €500, manager approval for higher amounts, and email notification on rejection."
-
----
-
-### `bpmn_read`
-
-Read a BPMN file and return its compact JSON representation.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `path` | yes | Path to the `.bpmn` file. |
-
-**Returns** Compact JSON with shape:
-```json
-{
-  "id": "process-id",
-  "processes": [{
-    "id": "...", "name": "...",
-    "elements": [
-      { "type": "startEvent", "id": "...", "name": "..." },
-      { "type": "serviceTask", "id": "...", "name": "...", "jobType": "com.example:do-thing:1" },
-      { "type": "userTask", "id": "...", "name": "...", "formId": "approve-form" },
-      { "type": "businessRuleTask", "id": "...", "name": "...", "decisionId": "credit-check" },
-      { "type": "exclusiveGateway", "id": "...", "name": "..." },
-      { "type": "endEvent", "id": "...", "name": "..." }
-    ]
-  }]
-}
-```
-
-Use `jobType` to identify service tasks for worker scaffolding. Use `formId` / `decisionId` to know which tasks need forms/DMN tables.
-
----
-
-### `bpmn_update`
-
-Update an existing BPMN by describing the change in natural language.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `path` | yes | Path to the `.bpmn` file. |
-| `instruction` | yes | What to change, e.g. "Add an error boundary event on the payment task that routes to a manual review lane." |
-
-**Returns** `{ path: string, updated: true }`
-
----
-
-### `bpmn_validate`
-
-Validate a BPMN file using the BPMNKit pattern advisor.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `path` | yes | Path to the `.bpmn` file. |
-
-**Returns**
-```json
-{
-  "summary": { "total": 3, "errors": 1, "warnings": 1, "info": 1, "autoFixable": 2 },
-  "findings": [
-    {
-      "severity": "error" | "warning" | "info",
-      "category": "string",
-      "message": "string",
-      "suggestion": "string",
-      "elementIds": ["..."],
-      "autoFixable": true
-    }
-  ]
-}
-```
-
-Errors block deployment. Warnings and info are advisory.
-
----
-
-### `bpmn_deploy`
-
-Deploy a BPMN process to a running engine.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `path` | yes | Path to the `.bpmn` file. |
-| `target` | yes | `"local"` — local reebe instance (uses `ZEEBE_ADDRESS`). `"camunda8"` — active Camunda 8 profile (set with `casen profile create`). |
-
-**Returns** `{ success: true, target: string, result: object }`
-
----
-
-### `bpmn_simulate`
-
-Structural analysis: validation findings + worker coverage check.
-
-> **Note:** Phase 1 only — structural analysis. Full process execution simulation is planned for a future phase.
+These are lightweight, CLI-only slash commands. For the full skill set — `/bpmnkit:implement`, `/bpmnkit:extend`, `/bpmnkit:agent`, `/bpmnkit:connect`, plus generated reference docs (`plan-format.md`, `connectors.md`, `agentic.md`, `feel.md`) — install the Claude Code plugin instead:
 
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `path` | yes | Path to the `.bpmn` file. |
-
-**Returns**
-```json
-{
-  "validation": { "errors": 0, "findings": [] },
-  "workerCoverage": {
-    "total": 3,
-    "covered": 2,
-    "missing": ["com.example:send-invoice:1"]
-  }
-}
+```sh
+/plugin marketplace add github:bpmnkit/monorepo
+/plugin install bpmnkit
 ```
 
 ---
 
-### `bpmn_run_history`
-
-Query recent process executions from the local proxy.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `processId` | no | Filter by process definition ID. |
-
-**Returns** `{ runs: [...] }` — up to 20 recent executions.
-
----
-
-## Worker tools
-
-### `worker_list`
-
-List all available workers: built-in BPMNKit workers and any scaffolded workers found in `./workers/`.
-
-**Parameters** none
-
-**Returns** `{ workers: [{ jobType, name, description, ... }], total: number }`
-
----
-
-### `worker_scaffold`
-
-Scaffold a TypeScript worker for a Zeebe job type. Generates `index.ts`, `package.json`, `tsconfig.json`, `README.md` in `./workers/<slug>/`.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `jobType` | yes | Zeebe job type string, e.g. `com.example:send-invoice:1`. |
-| `description` | no | What this worker does. |
-| `inputs` | no | Object mapping input variable names to type descriptions, e.g. `{ "invoiceId": "string", "amount": "number" }`. |
-| `outputs` | no | Object mapping output variable names to type descriptions. |
-
-**Returns** `{ path: string, files: [...], jobType: string, note: string }`
-
-After scaffolding: `cd workers/<slug> && npm install && npm start`. Edit `index.ts` to implement `handle()`.
-
----
-
-## Form & DMN tools
-
-### `form_create`
-
-Generate Camunda form JSON for all `userTask` elements in a BPMN that have a `formId`. Writes one `.form` file per task.
+## The pipeline
 
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `bpmnPath` | yes | Path to the `.bpmn` file. |
-| `outputDir` | no | Where to write form files (default: same directory as the BPMN). |
+Every process is authored as a `ProcessPlan` JSON file, never hand-written BPMN XML:
 
-**Returns**
-```json
-{
-  "forms": [
-    { "taskId": "...", "taskName": "...", "formId": "...", "path": "path/to/form-id.form" }
-  ]
-}
 ```
-
-Returns `{ "forms": [] }` if no user tasks with `formId` are found.
-
----
-
-### `dmn_create`
-
-Generate DMN decision table XML for all `businessRuleTask` elements in a BPMN that have a `decisionId`. Writes one `.dmn` file per task.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `bpmnPath` | yes | Path to the `.bpmn` file. |
-| `outputDir` | no | Where to write DMN files (default: same directory as the BPMN). |
-
-**Returns**
-```json
-{
-  "decisions": [
-    { "taskId": "...", "taskName": "...", "decisionId": "...", "path": "path/to/decision-id.dmn" }
-  ]
-}
+<name>.plan.json  →  casen synth  →  <name>.bpmn (+ <name>.bpmn.tests.json if plan.tests is set)
 ```
 
-Returns `{ "decisions": [] }` if no business rule tasks with `decisionId` are found.
-
----
-
-## Pattern tools
-
-### `pattern_list`
-
-List all available domain process patterns.
-
-**Parameters** none
-
-**Returns** `{ patterns: [{ id, name, description, keywords }], total: number }`
-
-Call this at the start of any skill to check whether a domain pattern applies. Match by comparing keywords against the user's request.
-
----
-
-### `pattern_get`
-
-Get the full content of a domain pattern: readme, worker specs, variations, and a compact BPMN template.
-
-**Parameters**
-| Name | Required | Description |
-|---|---|---|
-| `domain` | yes | Pattern id (e.g. `"invoice-approval"`) or free-text query (e.g. `"employee onboarding"`). |
-
-**Returns** `{ id, name, description, keywords, readme, workers, variations, template }`
-
-Pass `pattern.readme` and `pattern.workers` as additional context in the `description` parameter of `bpmn_create`.
+`casen plan schema` prints the full `ProcessPlan` format reference. `casen plan extract <file>.bpmn` lifts an existing process back into plan form (for `/extend`-style changes).
+
+## Key commands
+
+| Command | Does |
+|---|---|
+| `casen plan schema` | Print the `ProcessPlan` JSON format reference |
+| `casen plan extract <file>.bpmn` | Lift an existing process into `<file>.plan.json` |
+| `casen synth <plan>.json --output <file>.bpmn` | Compile a plan to laid-out, deployable BPMN |
+| `casen synth <plan>.json --merge <file>.bpmn --output <file>.bpmn` | Compile a delta plan and merge it into an existing process |
+| `casen connector search "<query>"` | Find a Camunda connector template by name/keyword |
+| `casen connector show <template-id>` | Required/optional input keys, task type, direction |
+| `casen lint lint <file>.bpmn` | Full static analysis (all categories) |
+| `casen lint lint <file>.bpmn --profile deploy` | Deploy-readiness gate — errors only |
+| `casen lint lint <file>.bpmn --fix` | Apply auto-fixable findings, write back |
+| `casen test <file>.bpmn` | Run scenarios from `<file>.bpmn.tests.json` |
+| `casen deploy deploy <file>.bpmn [--target camunda8]` | Deploy to local Reebe (default) or Camunda 8 |
+| `casen worker start` | Start every scaffolded worker in `./workers/` |
+
+## Conventions
+
+- A value starting with `=` is a FEEL expression; without it, it's a literal string.
+- Secrets always use the `{{secrets.NAME}}` placeholder — never a literal credential.
+- Every plan step's `id`/`name` should follow Camunda naming conventions ("Verb Object" tasks, "Object + past participle" start events, "?" gateway questions) — see the full plugin's `references/modeling-style.md` for the complete list.
+- Worker stubs use `@bpmnkit/worker-client`'s `createWorkerClient({ workerName }).poll(jobType)` API, written to `workers/<slug>/index.ts`.

package/skills/deploy.md

@@ -1,33 +1,36 @@
 ---
-description: Deploy a BPMN process to local reebe or Camunda 8
+description: Gate a BPMN process on deploy-readiness, then deploy it to local Reebe or Camunda 8.
 ---
 
 @.claude/aikit.md
 
-Deploy the BPMN process at the given path.
+Deploy the BPMN process: $ARGUMENTS
 
-## File to deploy
+Extract the `.bpmn` filename (find the single `.bpmn` in cwd, or ask, if not given) and destination (`--local` default, or `--camunda`).
 
-$ARGUMENTS
+## Step 1 — Gate on deploy-readiness
 
----
+```sh
+casen lint lint <file>.bpmn --profile deploy
+```
+
+If this reports any errors, stop and fix them first (or run `/review`) — do not deploy with deploy-profile errors.
+
+## Step 2 — Deploy
+
+```sh
+casen deploy deploy <file>.bpmn                     # local Reebe
+casen deploy deploy <file>.bpmn --target camunda8   # active Camunda 8 profile
+```
 
-1. Call `mcp__bpmnkit-aikit__bpmn_validate` on the file to check for errors before deploying.
-   - If there are errors, show them and ask: **"Fix errors first or deploy anyway?"**
-   - If warnings only: show them but proceed.
+Local deploy unreachable → tell the user to run `casen reebe start --port 26500` first, then retry. Camunda 8 deploy with no active profile → tell the user to run `casen profile create <name> --base-url <url> --auth-type bearer --token <token>` then `casen profile use <name>`, then retry.
 
-2. Ask: **"Deploy to local reebe or Camunda 8?"**
+## Step 3 — Verify and summarize
 
-3. Call `mcp__bpmnkit-aikit__bpmn_deploy` with the chosen target:
-   - `"local"` — deploys to the local reebe instance at ZEEBE_ADDRESS
-   - `"camunda8"` — deploys using the active casen profile (run `casen profile create` if not set up)
+```sh
+casen process-definition list --output json
+```
 
-4. Report the result:
-   - On success: "Deployed successfully. Process ID: <id>"
-   - On failure: show the error and suggest a fix (profile not set up, reebe not running, etc.)
+Report: `Deployed: <process-id>  version: <N>  target: <local|camunda8>`.
 
-5. If any scaffolded workers exist in ./workers/, remind:
-   ```
-   Don't forget to start your workers:
-     casen worker start
-   ```
+If any scaffolded workers exist in `./workers/`, remind: `casen worker start`. Remind about any `{{secrets.NAME}}` the process references — they must be provisioned in the target engine's secret store.

package/skills/implement.md

@@ -1,10 +1,10 @@
 ---
-description: Implement a BPMN process end-to-end from a natural language description
+description: Implement a BPMN process end-to-end from a natural language description — plan, compile, test, deploy.
 ---
 
 @.claude/aikit.md
 
-You are implementing a BPMN process end-to-end using BPMNKit AIKit tools. Work through these steps in order.
+You are implementing a BPMN process using `casen`. You never write BPMN XML by hand — every process is authored as a `ProcessPlan` JSON file and compiled with `casen synth`.
 
 ## Request
 
@@ -12,82 +12,48 @@ $ARGUMENTS
 
 ---
 
-## Step 1 — Check for a domain pattern
+## Step 1 — Resolve external interactions
 
-Call `mcp__bpmnkit-aikit__pattern_list` to see available domain patterns.
-If any pattern keywords match the request, call `mcp__bpmnkit-aikit__pattern_get` to load the full pattern as context for the next step.
+For each external system the process touches (Slack, email, HTTP, etc.): `casen connector search "<system>"` then `casen connector show <template-id>` for its required inputs. No match → use a plain `jobType` step (a worker gets scaffolded in Step 5).
 
----
-
-## Step 2 — Plan: Create the BPMN
-
-Spawn a subagent with this task:
+## Step 2 — Write the plan
 
-> Using the MCP tool `mcp__bpmnkit-aikit__bpmn_create`, generate a BPMN process for: **$ARGUMENTS**
->
-> If a domain pattern was loaded in Step 1, pass its readme and worker specs as additional context in the description parameter.
->
-> Return the file path of the generated BPMN.
-
----
+Write `<slug>.plan.json` per `casen plan schema`. Name elements clearly (see `.claude/aikit.md`'s naming conventions).
 
-## Step 3 — Implement: Wire workers
-
-Spawn a subagent with this task:
-
-> You are implementing workers for a BPMN process.
->
-> 1. Call `mcp__bpmnkit-aikit__worker_list` to get the catalog of available workers.
-> 2. Call `mcp__bpmnkit-aikit__bpmn_read` on the BPMN file from Step 2 to find all service task job types.
-> 3. For each service task job type:
->    - If a built-in or previously scaffolded worker matches: note it as "reused"
->    - If no match exists: call `mcp__bpmnkit-aikit__worker_scaffold` with the job type, a description, and expected inputs/outputs derived from the BPMN context
-> 4. Return: a list of `{ jobType, status: "reused" | "scaffolded", workerPath? }` for each service task
-
----
+## Step 3 — Compile
 
-## Step 4 — Review: Validate the BPMN
-
-Spawn a subagent with this task:
+```sh
+casen synth <slug>.plan.json --output <slug>.bpmn
+```
 
-> Call `mcp__bpmnkit-aikit__bpmn_validate` on the BPMN file from Step 2.
-> Identify any errors that block deployment and any warnings worth noting.
-> Return: `{ errors: [...], warnings: [...] }`
+Fix any reported problems in the plan (never the XML) and re-run — bounded to 2 retries before asking the user.
 
----
+## Step 4 — Test
 
-## Step 5 — Test: Check coverage
+Add a `tests` array to the plan covering the happy path and every branch/boundary, re-synth (writes `<slug>.bpmn.tests.json`), then:
 
-Spawn a subagent with this task:
+```sh
+casen test <slug>.bpmn
+```
 
-> Call `mcp__bpmnkit-aikit__bpmn_simulate` on the BPMN file from Step 2 with an empty scenarios array.
-> Return: worker coverage report (total service tasks, covered, missing)
+## Step 5 — Scaffold workers
 
----
+For every job-type step with no existing worker, write `workers/<slug>/index.ts` using `@bpmnkit/worker-client`'s `createWorkerClient({ workerName }).poll(jobType)` API.
 
 ## Step 6 — Present summary and ask to deploy
 
-Collect all results and present a summary:
-
 ```
 BPMN file: <path>
-Pattern used: <id or "none">
-
-Workers:
-  ✓ reused:     <list>
-  + scaffolded: <list with paths>
-
-Validation:
-  Errors:   <count> — <list if any>
-  Warnings: <count> — <list if any>
 
-Worker coverage: <covered>/<total> service tasks
+Connectors used: <list, with required secrets — never their values>
+Workers: reused <list> / scaffolded <list with paths>
+Tests: X/Y passed
 
 Scaffolded workers require: npm install && npm start (in each workers/<name>/ directory)
 ```
 
-Then ask: **"Deploy to local reebe, deploy to Camunda 8, or skip deployment?"**
+Then ask: **"Deploy to local Reebe, deploy to Camunda 8, or skip?"**
 
-- If "local": call `mcp__bpmnkit-aikit__bpmn_deploy` with `target: "local"`
-- If "camunda8": call `mcp__bpmnkit-aikit__bpmn_deploy` with `target: "camunda8"`
-- If "skip": done
+- local: `casen lint lint <slug>.bpmn --profile deploy` (must be zero errors) then `casen deploy deploy <slug>.bpmn`
+- camunda8: same lint gate, then `casen deploy deploy <slug>.bpmn --target camunda8`
+- skip: done