Penstock

Guide / Share and move

Refactoring across the project

Rename a variable, message, job type, decision or process in the diagrams, forms, templates, config, tests and code at once, with a preview of every edit first.

FreePro One rename is free, with no time limit. Bulk renames and extracting a subprocess are Pro.

What it does

A name often lives in many places: a message in two diagrams and a worker, a job type in a diagram, a template and the code. Refactoring changes all of them in one step. It always shows the plan first, and it applies exactly the plan it showed.

Rename

penstock refactor rename <kind> <old> <new>

The kind is one of: variable, message, signal, error, escalation, job-type, topic, decision, form, process. The last one is the process id, which is the called element of a call activity. The rename covers the BPMN, DMN and form files, the element templates, the application yaml and properties, the test cases and the code.

The command prints every edit with its file, line and before and after. It also prints every place it refuses to touch, and why: a script, a computed name, a filter or binding that hides the variable, an expression that does not parse, a link, a file outside the project, a file too large.

OptionWhat it does
(none)A preview only. Nothing is written.
--applyWrites the plan it has just shown.
--forceAllows applying when the git tree has uncommitted changes. Without it the command refuses.
--acknowledgeAllows applying when refused places remain. Without it the command refuses.
--format jsonPrints the same plan for a pipeline.

It also refuses when the new name already exists or is not a valid name for that kind.

Everything or nothing

--apply writes only the plan it has just shown. Every file is written whole and atomically, and only when it still reads as it did. If a write fails, all the files are put back. It follows no link and edits nothing outside the project root.

A single rename is free, with no time limit.

Bulk renames

Pro Team in a pipeline

penstock refactor bulk <mapping-file>

The mapping file is JSON with a renames list of kind, from and to, or lines of kind,old,new. The renames are applied in order, each on the result of the one before, with one plan and one atomic write.

Extract a subprocess

Pro Team in a pipeline

penstock refactor extract <file.bpmn> <ids> <new-process-id>

It moves one embedded subprocess, or a group of elements with exactly one way in and one way out, into a new process file next to the diagram, and puts a call activity in its place. The call is wired through variable mappings: zeebe:ioMapping on Camunda 8, camunda:in and camunda:out on Camunda 7. The drawing is moved, and the messages, signals, errors and escalations it references are copied.

It refuses, with the reason: a selection with several entries or exits, a condition on the way out, a boundary event without its task, compensation, a link event, a data object, a message flow or association across the edge, an expression it cannot read, a variable read by a computed name, a name that is already taken, and any result that would be less valid than the diagram was.

In the editors

Refactor… is in the More menu and the command palette of the BPMN, DMN and form editors in Penstock Web and Desktop. The plugins reach it through the same web editor. The dialog takes the kind, the old and the new name, or a list of renames, or a diagram, element ids and a new process id. It previews every edit by file and line and every place left alone, asks you to acknowledge the refused places, offers a way to apply over a dirty git tree, and then writes.

For an AI agent

The MCP tool refactor_rename is free. refactor_bulk and refactor_extract are Pro. Without apply they return the plan, and applying needs the planId of that preview, so an agent cannot write what it has not shown. They stay inside the project root of the client. See The MCP server.

Common problems

It refuses because the git tree has changes.
Commit or stash them, so the rename is one clean commit, or pass --force.
It lists places it will not touch.
Check each one by hand, then pass --acknowledge to apply the rest.