feat: comprehensive nanoflow support — CREATE, DROP, CALL, GRANT/REVOKE, SHOW ACCESS, MERMAID by retran · Pull Request #10 · retran/mxcli

retran · 2026-04-24T10:41:01Z

Why

Nanoflows are a core Mendix document type for mobile and offline-first apps. Until this PR, mxcli had read-only nanoflow support (SHOW, DESCRIBE) but could not create, modify, or manage nanoflows — blocking agentic workflows that need to scaffold, refactor, or secure nanoflow logic.

This gap was visible in the feature matrix: nanoflows lagged far behind microflows in every dimension. This PR brings nanoflows to full feature parity with microflows across grammar, executor, SDK, validation, visualization, and security management.

Proposal: docs/11-proposals/PROPOSAL_nanoflow_support.md
Test plan: docs/15-testing/nanoflow-test-cases.md (18 sections, 123 test cases)

What Changed

New MDL commands

Command	Description
`CREATE [OR MODIFY] NANOFLOW`	Create nanoflows with body, parameters, return type, folder placement
`DROP NANOFLOW`	Remove a nanoflow from the project
`CALL NANOFLOW`	Call a nanoflow from within a flow body (valid in both microflows and nanoflows)
`CALL JAVASCRIPT ACTION`	Call a JavaScript action from within a flow body
`GRANT EXECUTE ON NANOFLOW`	Grant module role access to a nanoflow
`REVOKE EXECUTE ON NANOFLOW`	Revoke module role access from a nanoflow
`SHOW ACCESS ON NANOFLOW`	Display which roles have access to a nanoflow
`MOVE NANOFLOW`	Move a nanoflow to a different module or folder
`RENAME NANOFLOW`	Rename a nanoflow
`DIFF` (nanoflow support)	Detect and display nanoflow changes between `.mpr` versions

CLI enhancements

describe nanoflow --format mermaid — generates Mermaid flowchart diagrams for nanoflows (same --format flag already supported for microflows and domain models)

Validation

Type-switch validation rejects 21 actions that Mendix does not allow in nanoflows (e.g., database commit, Java actions, import/export). Entity resolver errors propagate upfront — no silent failures on invalid parameter or return types.

Bug fixes and improvements

JavaScript action support: call javascript action Module.ActionName(params) — grammar rule, parser, AST node, visitor, builder, validation, serializer. JS actions roundtrip correctly through describe → drop → create cycle.
Association retrieve roundtrip: retrieve $X from $Y/Module.Association syntax preserved on roundtrip. Previously, the builder converted association retrieves to database retrieves with XPath constraints on reverse traversals.
Nanoflow serialization rewrite: serializeNanoflow() was incomplete — missing ReturnType, ObjectCollection, and Flows. Created nanoflows lost their body when written to .mpr.
Empty-then optimization: If/else blocks with empty true branches are swapped and condition negated for readable DESCRIBE output.
NanoflowCallAction BSON field corrected from ResultVariableName to OutputVariableName.
JavaScript action references validated separately from Java actions.
Module existence validated for SHOW NANOFLOWS/MICROFLOWS.
Numeric return literals no longer get spurious $ prefix.
Empty nanoflow/microflow names rejected at create time.
NanoflowCallAction error handling type resolved correctly.
not() expression spacing preserved on roundtrip.
Mermaid renderer handles NanoflowCallAction.
AllowedModuleRoles preserved through drop/recreate cycle.

Agentic skill

New Claude Code skill at .claude/skills/mendix/write-nanoflows.md — guides AI agents through nanoflow creation with MDL syntax, parameter types, body actions, security management, and validation rules.

Shared helpers

buildEntityNames extracted to eliminate duplication between microflow and nanoflow Mermaid rendering.
serializeNanoflow() fully rewritten to serialize body, flows, return type, and parameters.

Testing

Automated tests (all pass with make build && make test && make lint-go):

33 integration tests (roundtrip_nanoflow_test.go) — CREATE, DROP, CALL, GRANT/REVOKE, SHOW, MOVE, RENAME, MERMAID, validation, error paths
36 mock unit tests (cmd_nanoflows_mock_test.go) — not-connected guards, duplicate handling, idempotent grant/revoke, all 21 disallowed actions, nested body validation
5 BSON roundtrip tests (roundtrip_test.go) — parse→serialize→parse cycle with activities, flows, and roles

Manual testing: 18-section test plan (123 test cases) executed against 3 App Gallery demo projects (223 nanoflows total). All tests pass except 2 inconclusive (no test data for page integration scenarios).

Known limitations

Description	Status
Expression whitespace normalization (e.g. `find($x,'y')` → `find($x, 'y')`)	Cosmetic — accepted as canonical formatting
Security roles persist through drop/recreate	By design — matches microflow behavior
Dangling call reference after callee drop renders stale name	By design — no cascading deletes

Documentation updated

MDL_FEATURE_MATRIX.md — nanoflow row reflects implemented state
MDL_QUICK_REFERENCE.md — added CREATE, MOVE, GRANT/REVOKE, SHOW ACCESS nanoflow syntax
01-language-reference.md — added CREATE/DROP/GRANT/REVOKE nanoflow sections
grammar-reference.md — added createNanoflowStatement, dropNanoflowStatement, callJavaScriptActionStatement
PROPOSAL_nanoflow_support.md — rewritten from proposal to feature description
nanoflow-test-cases.md — comprehensive QA test plan (18 sections, 123 test cases)
10-bson-mapping.md — added Nanoflow Mapping section with type differences, allowed actions, JS action field mapping
examples/create_nanoflow/ — new Go example with 4 nanoflow patterns
CHANGELOG.md — unreleased entries for all nanoflow features
SDK_EQUIVALENCE.md — updated nanoflow CRUD feature list

Stats

79 files changed, +18,227 / −10,284 lines, 8 commits

Grammar → AST → Visitor → Executor → SDK → Tests → Docs — full pipeline coverage.

Copilot

Pull request overview

Adds end-to-end nanoflow support to mxcli/MDL to reach parity with existing microflow functionality, spanning grammar/AST, executor behavior, SDK BSON parsing/writing, Mermaid rendering, and test/docs updates.

Changes:

Extends MDL grammar + AST + visitors to support CREATE/DROP NANOFLOW, CALL NANOFLOW (in flow bodies), GRANT/REVOKE EXECUTE ON NANOFLOW, and SHOW ACCESS ON NANOFLOW.
Implements executor handlers for nanoflow lifecycle + access control + Mermaid rendering, plus validation and reference-checking updates.
Adds SDK nanoflow parsing/serialization (including NanoflowCallAction) and roundtrip tests, plus new documentation and test plans.

Reviewed changes

Copilot reviewed 53 out of 56 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
sdk/mpr/writer_security_test.go	Minor formatting fix in existing security writer test.
sdk/mpr/writer_microflow_actions.go	Adds BSON serialization for `Microflows$NanoflowCallAction`.
sdk/mpr/writer_microflow.go	Implements nanoflow BSON serialization including flows/return type/object collection.
sdk/mpr/roundtrip_test.go	Adds nanoflow roundtrip tests (baseline + synthetic).
sdk/mpr/parser_nanoflow.go	Parses `AllowedModuleRoles` for nanoflows.
sdk/mpr/parser_microflow_actions.go	Adds parser for `NanoflowCallAction`.
sdk/mpr/parser_microflow.go	Registers `Microflows$NanoflowCallAction` parser.
sdk/microflows/microflows_actions.go	Introduces SDK types: `NanoflowCallAction`, `NanoflowCall`, mappings.
sdk/microflows/microflows.go	Adds `AllowedModuleRoles` to `Nanoflow` model.
mdl/visitor/visitor_security.go	Builds GRANT/REVOKE nanoflow access AST statements.
mdl/visitor/visitor_query.go	Extends SHOW ACCESS to include NANOFLOW.
mdl/visitor/visitor_microflow_statements.go	Allows `CALL NANOFLOW` in flow body statements + annotations wiring.
mdl/visitor/visitor_microflow_actions.go	Builds `CallNanoflowStmt` from parse tree.
mdl/visitor/visitor_microflow.go	Builds `CreateNanoflowStmt` from parse tree.
mdl/visitor/visitor_entity.go	Extends DROP to include NANOFLOW.
mdl/grammar/parser/mdlparser_listener.go	Generated listener interface updates for new productions.
mdl/grammar/parser/mdlparser_base_listener.go	Generated base listener updates for new productions.
mdl/grammar/MDLParser.g4	Adds grammar for create/call nanoflow + access grant/revoke + SHOW ACCESS ON NANOFLOW.
mdl/executor/validate_microflow.go	Treats `CallNanoflowStmt` like other statements for naming/vars/error-handling.
mdl/executor/validate.go	Tracks nanoflow defs; validates nanoflow bodies; adds nanoflow forward-ref/ref checks.
mdl/executor/stmt_summary.go	Adds summaries for nanoflow grant/revoke statements.
mdl/executor/roundtrip_nanoflow_test.go	Integration tests (build tag) covering nanoflow commands end-to-end.
mdl/executor/registry_test.go	Registers new nanoflow statement types in known-statement list.
mdl/executor/registry.go	Routes registration via combined microflow/nanoflow handler registrar.
mdl/executor/register_stubs.go	Registers create/drop nanoflow and security handlers.
mdl/executor/nanoflow_validation.go	Adds nanoflow-specific body/return-type validation.
mdl/executor/executor_query.go	Wires SHOW ACCESS ON NANOFLOW execution.
mdl/executor/executor.go	Adds executor caches for created/dropped nanoflows.
mdl/executor/exec_context.go	Tracks created nanoflows in executor session cache.
mdl/executor/cmd_security_write.go	Implements GRANT/REVOKE EXECUTE ON NANOFLOW.
mdl/executor/cmd_security.go	Implements SHOW ACCESS ON NANOFLOW.
mdl/executor/cmd_nanoflows_mock_test.go	Adds mock-based unit tests for nanoflow commands/validation.
mdl/executor/cmd_nanoflows_drop.go	Implements DROP NANOFLOW execution.
mdl/executor/cmd_nanoflows_create.go	Implements CREATE (OR MODIFY) NANOFLOW execution + graph building.
mdl/executor/cmd_microflows_format_action.go	Formats `NanoflowCallAction` in DESCRIBE output.
mdl/executor/cmd_microflows_builder_validate.go	Adds builder validation for `CallNanoflowStmt` outputs/error blocks.
mdl/executor/cmd_microflows_builder_graph.go	Adds graph builder dispatch for `CallNanoflowStmt`.
mdl/executor/cmd_microflows_builder_calls.go	Builds `NanoflowCallAction` from `CALL NANOFLOW` statements.
mdl/executor/cmd_microflows_builder_annotations.go	Exposes annotations for `CallNanoflowStmt`.
mdl/executor/cmd_microflows_builder.go	Adds backend lookup for nanoflow return types.
mdl/executor/cmd_mermaid_mock_test.go	Updates Mermaid unsupported-type test now that nanoflow is supported.
mdl/executor/cmd_mermaid.go	Adds Mermaid rendering for nanoflows and shares entity-name building logic.
mdl/executor/cmd_diff_mdl.go	Adds diff rendering for `CallNanoflowStmt`.
mdl/ast/ast_security.go	Adds AST statement types for nanoflow grant/revoke access.
mdl/ast/ast_query.go	Adds `ShowAccessOnNanoflow` enum value.
mdl/ast/ast_microflow.go	Adds `CreateNanoflowStmt`, `DropNanoflowStmt`, `CallNanoflowStmt`.
docs/15-testing/nanoflow-test-cases.md	Adds comprehensive manual test plan (needs updates per review comments).
docs/11-proposals/show-describe-nanoflows.md	Marks older proposal as superseded.
docs/11-proposals/PROPOSAL_nanoflow_support.md	Adds consolidated proposal doc (needs updates per review comments).
docs/06-mdl-reference/grammar-reference.md	Documents `createNanoflowStatement` in grammar reference.
docs/05-mdl-specification/01-language-reference.md	Adds language-reference entries for nanoflow commands (needs updates per review comments).
docs/01-project/MDL_QUICK_REFERENCE.md	Adds quick reference entries for nanoflow commands (needs updates per review comments).
docs/01-project/MDL_FEATURE_MATRIX.md	Updates feature matrix to reflect nanoflow support + Mermaid.
.claude/skills/mendix/write-nanoflows.md	Adds “write nanoflows” skill doc (contains inaccuracies per review comments).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 53 out of 56 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 53 out of 56 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 53 out of 56 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 73 out of 76 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 73 out of 76 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 73 out of 76 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 73 out of 76 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

… and proposal

- SHOW ACCESS ON NANOFLOW — query nanoflow security grants - DESCRIBE MERMAID for nanoflows via CLI --format mermaid - Nanoflow diff support — unified diff output for modified nanoflows - JavaScript action BSON parsing (read path) - NanoflowCallAction formatter for DESCRIBE output - Hard-code nanoflow $Type to "Microflows$Nanoflow" - Preserve AllowedModuleRoles through drop/recreate cycles - Validate module existence, numeric return types, empty names - Normalize empty-then branches in DESCRIBE for readable if/else - Expression spacing fix (not() parenthesization)

- Document intentional behaviors in nanoflow test plan - Add nanoflow references to ARCHITECTURE, CLAUDE, CHANGELOG - Update MDL_FEATURE_MATRIX, MDL_QUICK_REFERENCE, language reference - Add nanoflow examples to agentic skills (security, pages, validation) - Add nanoflow MDL examples to doctype-tests

@excluded

- Propagate describeNanoflow errors in diff command - Match create-or-modify pattern in diff output - Add nanoflow-specific fields (@excluded, folder, comment) to MDL output - Guard empty-then swap edge case in if/else normalization - Handle missing JS action references gracefully in formatter - Harden negation expression rendering

…e fix Full pipeline for `call javascript action` syntax: - Grammar rule, AST node, visitor, builder, validator, BSON serializer - JavaScript actions allowed in nanoflows (client-side), disallowed check skips them correctly - Separate JS action reference validation from Java action validation Association retrieve roundtrip fix: - Preserve AssociationRetrieveSource on roundtrip instead of converting to DatabaseRetrieveSource with XPath for reverse traversals

…ixes - Add Nanoflow Mapping section to BSON mapping documentation - Add create_nanoflow Go example with 4 nanoflow patterns - Update CHANGELOG with JS action syntax and association retrieve entries - Add nanoflow datasource option to create-page skill - Update SDK_EQUIVALENCE nanoflow feature list - Exhaustive nanoflow denylist test (21 disallowed + JS action allowed) - Document denylist ordering dependency in error handling - Fix isNumericLiteral: reject trailing dot ("5." → false)

This was referenced Apr 24, 2026

feat: add CREATE/DROP NANOFLOW support #7

Closed

feat: CALL NANOFLOW + GRANT/REVOKE nanoflow access #8

Closed

feat: add SHOW ACCESS ON NANOFLOW and DESCRIBE MERMAID for nanoflows #9

Closed

retran force-pushed the pr4-nanoflows-all branch 5 times, most recently from aafbfae to 993bd47 Compare April 24, 2026 11:47

retran requested a review from Copilot April 24, 2026 11:56

Copilot started reviewing on behalf of retran April 24, 2026 11:56 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

retran force-pushed the pr4-nanoflows-all branch 2 times, most recently from 381769d to 513582a Compare April 24, 2026 12:22

retran requested a review from Copilot April 24, 2026 12:25

Copilot started reviewing on behalf of retran April 24, 2026 12:26 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Comment thread sdk/mpr/roundtrip_test.go

Comment thread mdl/executor/cmd_nanoflows_create.go Outdated

Comment thread mdl/executor/roundtrip_nanoflow_test.go

retran force-pushed the pr4-nanoflows-all branch 2 times, most recently from 69fc322 to 2692d87 Compare April 24, 2026 12:51

retran requested a review from Copilot April 24, 2026 12:52

Copilot started reviewing on behalf of retran April 24, 2026 12:52 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Comment thread mdl/executor/cmd_nanoflows_create.go

Comment thread docs/11-proposals/show-describe-nanoflows.md

Comment thread sdk/mpr/writer_microflow.go

retran force-pushed the pr3-type-assertion-hardening branch from 72a49c8 to c66c06e Compare April 24, 2026 13:12

retran force-pushed the pr4-nanoflows-all branch 2 times, most recently from 8f21363 to e36b9ae Compare April 24, 2026 13:22

retran requested a review from Copilot April 24, 2026 13:23

Copilot started reviewing on behalf of retran April 24, 2026 13:23 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

retran requested a review from Copilot April 24, 2026 17:58

Copilot started reviewing on behalf of retran April 24, 2026 17:58 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Comment thread mdl/executor/cmd_diff.go Outdated

Comment thread mdl/executor/cmd_diff_mdl.go

Comment thread mdl/executor/cmd_microflows_format_action.go

retran force-pushed the pr4-nanoflows-all branch from 2cb4ef0 to b89c720 Compare April 24, 2026 18:04

retran force-pushed the pr3-type-assertion-hardening branch from c66c06e to 42ffd35 Compare April 24, 2026 18:04

retran force-pushed the pr4-nanoflows-all branch from b89c720 to 6d1aaec Compare April 24, 2026 18:05

retran force-pushed the pr3-type-assertion-hardening branch from 42ffd35 to acb3107 Compare April 24, 2026 18:05

retran requested a review from Copilot April 24, 2026 18:09

Copilot started reviewing on behalf of retran April 24, 2026 18:09 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Comment thread sdk/mpr/parser_microflow.go

Comment thread sdk/mpr/writer_microflow_actions.go

Comment thread mdl/executor/cmd_microflows_format_action.go

retran requested a review from Copilot April 24, 2026 18:16

Copilot started reviewing on behalf of retran April 24, 2026 18:16 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

Comment thread sdk/mpr/writer_microflow_actions.go

Comment thread sdk/mpr/writer_microflow.go

retran requested a review from Copilot April 24, 2026 18:26

Copilot started reviewing on behalf of retran April 24, 2026 18:27 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

retran force-pushed the pr4-nanoflows-all branch 2 times, most recently from 5b17c36 to 2a0f486 Compare April 24, 2026 20:00

retran force-pushed the pr3-type-assertion-hardening branch from acb3107 to 62b5a16 Compare April 24, 2026 20:06

retran force-pushed the pr4-nanoflows-all branch from 2a0f486 to 3ff3064 Compare April 24, 2026 20:06

retran added 7 commits April 24, 2026 22:31

feat: add CREATE/DROP NANOFLOW support — grammar, AST, visitor, executor

02994d0

feat: add CALL NANOFLOW, GRANT/REVOKE nanoflow access, agentic skill,…

cb2c7fc

… and proposal

rewrite nanoflow test cases as QA manual test documentation

66f44b2

retran force-pushed the pr4-nanoflows-all branch from 3ff3064 to 74e5ea1 Compare April 24, 2026 20:33

retran force-pushed the pr4-nanoflows-all branch from 74e5ea1 to 8b23f02 Compare April 24, 2026 20:33

retran changed the base branch from pr3-type-assertion-hardening to main April 24, 2026 20:34

Conversation

retran commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What Changed

New MDL commands

CLI enhancements

Validation

Bug fixes and improvements

Agentic skill

Shared helpers

Testing

Known limitations

Documentation updated

Stats

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

retran commented Apr 24, 2026 •

edited

Loading