Penstock

Command line / Editors without a plugin

penstock lsp

A language server for BPMN, DMN, CMMN and Camunda Form files, so an editor that speaks the Language Server Protocol shows the Penstock findings without a plugin.

Free The penstock command on the PATH of the editor, which needs Node.js 22.22.2 or later in 22, 24.15.0 or later in 24, or 26 and later.

What it is

penstock lsp [--stdio] is a Language Server Protocol 3.17 server built on the same check engine and project model as penstock check. An editor starts it, talks to it over standard input and output, and shows the findings where they are. It is how Zed, Helix, Neovim, Sublime Text, Emacs with eglot, Kate and Eclipse with LSP4E show Penstock. None of them has a Penstock plugin, and none is needed. It is Free.

Stdio is the only transport. --socket, --pipe, --node-ipc and a port are refused. The server makes no network call, executes nothing from the files it reads, and writes only protocol frames to standard output. Started by hand in a terminal it exits with 1; the editor starts it.

JetBrains IDEs and VS Code have their own Penstock plugins, with the full editor; this server is for the editors that have none.

What it does

RequestAnswer
DiagnosticsThe penstock check findings of the open buffer, never the file on disk, with real ranges: elements by id, decision table rules by number, form components by id, and a parse error at its position. The code is the rule id, a link opens the rule page, and a finding with more than one place carries related places. Typing is debounced by 300 ms, and a stale run is dropped.
HoverThe rule under a diagnostic, with why it matters and how to fix it. For any element: its type, id, name, called process, called decision, form, job type and the variables in scope.
Go to definition, referencesA call activity to its process, a decision reference to the decision, a form reference to the form file, and message, signal and error names to their other uses in the project.
Symbols and foldingProcesses, sub-processes, lanes, tasks, events, gateways, DMN decisions with inputs and outputs, form components and CMMN plan items, for the document and for the workspace. Every element that has children and spans lines folds.
Quick fixesMark a process executable, set the history time to live, delete a superfluous label, and open the rule documentation.
CompletionFEEL built-ins, keywords and the variables the project knows, in = expressions, conditions and DMN cells; process, decision and form ids where a reference is expected.

What it does not do

Limits

A document over 16 MiB is not read, and says so once. A file shows at most 200 findings, and the last note says so. A message over 32 MiB is refused. At most 256 documents are open, and the project index reads at most 3000 files of at most 4 MiB each. A file is read only inside the workspace folders the editor gave, after symbolic links are resolved; a file outside them gets one note and is not checked. A file that is not well formed gets one error at the position of the parse error.

Set it up

Install the command line first (Command line) and check that penstock --version works in the shell your editor starts from. In every setup below the editor runs penstock lsp --stdio. A BPMN, DMN or CMMN file is XML and a .form file is JSON, so each setup maps those file types to the server. An editor's own settings change between versions, so check these against its documentation.

Neovim 0.11

vim.lsp.config('penstock', {
  cmd = { 'penstock', 'lsp', '--stdio' },
  filetypes = { 'bpmn', 'dmn', 'cmmn', 'camunda-form' },
  root_markers = { 'penstock.yaml', '.git' },
})
vim.lsp.enable('penstock')
vim.filetype.add({ extension = { bpmn = 'bpmn', dmn = 'dmn', cmmn = 'cmmn', form = 'camunda-form' } })

Helix

In languages.toml:

[language-server.penstock]
command = "penstock"
args = ["lsp", "--stdio"]

[[language]]
name = "bpmn"
scope = "source.bpmn"
file-types = ["bpmn", "dmn", "cmmn", "form"]
roots = ["penstock.yaml", ".git"]
language-servers = ["penstock"]
grammar = "xml"

Zed

Zed has no Penstock extension. In settings.json:

{
  "languages": { "XML": { "language_servers": ["penstock", "..."] } },
  "lsp": { "penstock": { "binary": { "path": "penstock", "arguments": ["lsp", "--stdio"] } } },
  "file_types": { "XML": ["bpmn", "dmn", "cmmn"], "JSON": ["form"] }
}

Sublime Text

In the settings of the LSP package:

{
  "clients": {
    "penstock": {
      "enabled": true,
      "command": ["penstock", "lsp", "--stdio"],
      "selector": "text.xml | source.json",
      "schemes": ["file"]
    }
  }
}

Emacs, eglot

(add-to-list 'auto-mode-alist '("\\.\\(bpmn\\|dmn\\|cmmn\\)\\'" . nxml-mode))
(add-to-list 'auto-mode-alist '("\\.form\\'" . json-mode))
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '((nxml-mode json-mode) . ("penstock" "lsp" "--stdio"))))

Kate

In Settings, LSP Client, User Server Settings:

{ "servers": { "xml": { "command": ["penstock", "lsp", "--stdio"], "highlightingModeRegex": "^XML$" } } }

Eclipse, LSP4E

Eclipse has no Penstock plugin. Under Preferences, Language Servers, choose Add, pick the content types XML and JSON, and set the launch configuration to Program with the command penstock and the arguments lsp --stdio. Then associate *.bpmn, *.dmn, *.cmmn and *.form with them.

OpenIDEA

The OpenIDEA plugin is not released. Its package starts penstock lsp, but there is nothing to install yet, so use one of the editors above.

What you see

Common problems

No findings appear.
Check that the editor started the server (most editors have a log of language servers) and that penstock is on the PATH the editor sees; an editor started from a menu may not have the PATH of your shell. The file must be inside a workspace folder the editor gave.
The file opens as plain XML and nothing is attached to it.
The editor has to map the file types to the server, as in the setups above. A .form file is JSON.
"Only 200 findings are shown".
A file shows at most 200 findings. Fix the first ones, or run penstock check for the whole list.
A custom bpmnlint rule does not show.
The server runs no code from the project. penstock check runs your custom rules.
Started in a terminal, it exits at once.
It speaks only over standard input and output to an editor, and exits with 1 in a terminal.