Add support for Nanoflows

[ako]

Nanoflows are needed to run logic in the browser or on a mobile device.

[github-actions]

Issue Triage

Summary:
The request is to add mxcli support for editing or processing Nanoflows in Mendix projects.

Checklist for feature request

Required info	Present?	Details
Use case – why the feature is needed / problem it solves	✅ (briefly mentioned: Nanoflows run logic in browser/mobile)	Could be expanded with a concrete scenario.
Proposed syntax or behavior (if applicable)	❌	No description of how mxcli should handle Nanoflows (e.g., new commands, flags, output format).
Mendix version relevance (if version‑specific)	❌	No indication of which Mendix versions the feature should target.

Next steps:
Could you please add a bit more detail?

1. Use case: Explain a specific situation where you need mxcli to work with Nanoflows (e.g., generating reports, applying bulk changes, CI/CD pipelines).
2. Proposed behavior: Describe what you’d like mxcli to do—new sub‑commands, options, or changes to existing output when Nanoflows are present.
3. Mendix version: Let us know which Mendix version(s) you’re targeting (e.g., 9.x, 10.x) so we can ensure compatibility.

Thanks for the suggestion! Once we have those details we can move forward.

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The enhancement request lacks critical details needed for implementation. Please clarify:

1. Mendix version: Nanoflow behavior and BSON structure may vary between Mendix versions (e.g., pre-10.0 vs 10.0+). Which version should this target?
2. Desired MDL syntax: Should nanoflows mirror microflow syntax (e.g., CREATE NANOFLOW ... BEGIN ... END) or have unique constructs? The request mentions "run logic in browser/mobile" but doesn't specify if this affects syntax.
3. Specific operations needed: Do you require full CRUD support (SHOW/DESCRIBE/CREATE/ALTER/DROP), or just certain operations? The feature matrix shows SHOW NANOFLOWS already works, but DESCRIBE/CREATE are missing.
4. Example nanoflow: Provide a simple example of what you want to create (e.g., a nanoflow that shows a page or calls a microflow) to validate syntax and BSON mapping.

Without this, we risk implementing syntax that doesn't match your use case or Mendix's actual BSON structure.

Overlap Check

Partial support already exists:

• SHOW NANOFLOWS [IN Module] works (per feature matrix and current implementation status)
• Nanoflows are likely visible in CATALOG.MICROFLOWS or similar tables since they share metadata with microflows
• However, DESCRIBE, CREATE, ALTER, and DROP for nanoflows are not implemented (matrix shows all N except SHOW)
• No existing MDL syntax fully covers nanoflow creation/modification – this requires new statements

Proposed MDL Syntax

Following MDL design guidelines (reads as English, standard CRUD verbs, qualified names), nanoflows should mirror microflow syntax since they share the same metamodel base (Microflows$Microflow in BSON). Proposed syntax:

-- Create a nanoflow with parameters and return type
CREATE NANOFLOW Module.MyNanoflow(
    Input: String,
    Count: Integer
) RETURNS Boolean AS $Result
BEGIN
  // Example: Show a page
  SHOW PAGE Module.MyPage ($Param = $Input);
  
  // Example: Call a microflow
  $Success = CALL MICROFLOW Module.ValidateInput(Value: $Input);
  
  RETURN $Success;
END;

-- Call a nanoflow from a microflow (already partially supported)
$Result = CALL NANOFLOW Module.MyNanoflow(Input: "test", Count: 5);

Evaluation against guidelines:

• ✅ Reads as English: "CREATE NANOFLOW Module.MyNanoflow ..."
• ✅ Uses standard CREATE verb (not ADD or DEFINE)
• ✅ Qualified names required (Module.MyNanoflow)
• ✅ Property format uses ( Key: value, ... ) with colons
• ✅ One example sufficient for LLM to generate variants (e.g., change return type, add parameters)
• ✅ Diff-friendly: Adding a parameter is one-line change

Implementation Roadmap

Follow the full-stack pipeline. Specific files to modify:

1. Grammar (mdl/grammar/)

• MDLLexer.g4: Add NANOFLOW token (alphabetically ordered)

  NANOFLOW: N A N O F L O W;

• MDLParser.g4:
  • Add nanoflowStatement alternative to microflowStatement (since nanoflows reuse microflow infrastructure)
  • Define rule mirroring microflowStatement but with NANOFLOW keyword
  • Reuse existing microflow clauses (parameters, return type, BEGIN/END, statements)

  nanoflowStatement
      : (VARIABLE EQUALS)? NANOFLOW qualifiedName nanoflowSignature nanoflowBody
      ;
  nanoflowSignature
      : LPAREN nanoflowParamList? RPAREN (RETURNS typeSpec EQUALS VARIABLE)?
      ;
  nanoflowParamList
      : nanoflowParam (COMMA nanoflowParam)*
      ;
  nanoflowParam
      : IDENTIFIER COLON typeSpec
      ;
  nanoflowBody
      : BEGIN microflowStatementList END
      ;

• Run make grammar to regenerate parser

2. AST (mdl/ast/ast_microflow.go)

• No new AST types needed – nanoflows reuse MicroflowStmt since they share structure
• Add Nanoflow constant to MicroflowType enum if distinguishing execution context (optional)

  type MicroflowType int
  const (
      MicroflowTypeUndefined MicroflowType = iota
      MicroflowTypeMicroflow
      MicroflowTypeNanoflow
  )

3. Visitor (mdl/visitor/visitor_microflow_statements.go)

• Add case in buildMicroflowStatement for NANOFLOW:

  case ctx.NanoflowStatement() != nil:
      return buildMicroflowStatement(ctx.NanoflowStatement()) // Reuse microflow builder

• No changes to buildMicroflowStatement helper – it already handles parameters, return type, body

4. SDK Types (sdk/microflows/)

• Nanoflows are represented by existing Microflow struct – no changes needed
• Verify Microflow.Type field distinguishes nanoflows (check reflection data)
• If needed, add IsNanoflow() helper:

  func (m *Microflow) IsNanoflow() bool {
      return m.Type == "Nanoflow" // Verify actual storage name
  }

5. BSON Parser/Writer (sdk/mpr/parser_microflow.go & writer_microflow.go)

• Investigation first: Confirm nanoflow $Type storage name (see BSON Investigation below)
• Parser: No changes if nanoflows use same structure as microflows (likely)
• Writer: Ensure SerializeMicroflow sets correct $Type based on Microflow.Type

  func serializeMicroflow(mf *microflows.Microflow) bson.D {
      // ...
      bsonType := "Microflows$Microflow" // Default
      if mf.IsNanoflow() {
          bsonType = "Microflows$Nanoflow" // Verify actual name
      }
      doc := bson.D{
          {Key: "$Type", Value: bsonType},
          // ... rest
      }
      // ...
  }

6. Executor (mdl/executor/)

• Builder (cmd_microflows_builder.go):
  • No changes – addMicroflow already handles nanoflows if $Type is correct
  • Verify error handling distinguishes nanoflows for messages
• Show (cmd_microflows_show.go):
  • Add case for nanoflows in formatMicroflowStatement (reuse microflow formatting)
  • Ensure DESCRIBE NANOFLOW outputs valid MDL
• Catalog (mdl/catalog/tables.go):
  • Nanoflows likely already in MICROFLOWS table – verify Type column filtering
  • If separate table needed, add NANOFLOWS catalog table (unlikely)

7. Testing

• Add doctest to mdl-examples/doctype-tests/02-microflow-examples.mdl:

  CREATE NANOFLOW NanoflowExamples.SimpleReturn()
  RETURNS Boolean AS $Result
  BEGIN
    $Result = true;
    RETURN $Result;
  END;
  

• Add roundtrip test in mdl/executor/roundtrip_test.go:

  func TestNanoflowRoundtrip(t *testing.T) {
      // Create via MDL, DESCRIBE, re-parse, compare
  }

BSON Investigation

Nanoflows are stored as Microflows$Microflow documents with a Type field distinguishing them from microflows. Steps to confirm:

1. Create test nanoflow in Studio Pro:

   • Make a simple nanoflow (e.g., no parameters, returns constant)
   • Save project

2. Find document ID:

   ./bin/mxcli -p test.mpr -c "SELECT Id, QualifiedName, Type FROM CATALOG.MICROFLOWS WHERE QualifiedName = 'Module.MyNanoflow'"

3. Dump raw BSON:

   go run ./cmd/debug/main.go test.mpr <document-id-from-step-2>

4. Key fields to verify:

   • $Type: Should be Microflows$Microflow (same as microflows)
   • Type field: Likely "Nanoflow" (storage name) vs qualified name "Module.MyNanoflow"
   • Structure: Identical to microflows (ObjectCollection → ActionActivity → etc.)
   • Defaults: Check if any nanoflow-specific defaults exist (e.g., ExecuteAsync)

5. Reflection data check:

   • Examine reference/mendixmodellib/reflection-data/v10.0.0/microflows.xml
   • Look for Microflow element and Type enumeration
   • Confirm storage name for nanoflow type

Expected outcome: Nanoflows reuse microflow BSON structure with a Type: "Nanoflow" field. No new parser/writer logic needed – only ensure executor sets/reads this field correctly.

Testing Strategy

• Doctest: Add nanoflow CREATE example to 02-microflow-examples.mdl (as above)
• mx check validations:
  • mxcli check should accept nanoflow syntax without errors
  • mxcli check -p app.mpr --references validates qualified names exist
• Integration tests:
  1. Create nanoflow via MDL in test project
  2. DESCRIBE nanoflow and verify output is valid MDL
  3. Roundtrip: DESCRIBE output → re-parse → identical AST
  4. Call nanoflow from microflow via MDL (CALL NANOFLOW)
  5. Verify project opens in Studio Pro without CE errors
• Existing test suite: Run make test to ensure no regressions

Gotchas & Risks

• Storage name vs qualified name:

  • The Type BSON field uses storage name ("Nanoflow"), not qualified name ("Module.MyNanoflow").
  • Risk: Using wrong string in $Type causes TypeCacheUnknownTypeException in Studio Pro.
  • Fix: Verify storage name via BSON dump (Step 4 above).

• Missing BSON defaults:

  • Nanoflows may require specific default values (e.g., ExecuteAsync: false).
  • Risk: Omitting defaults causes Studio Pro to mark nanoflow as "out of date".
  • Fix: Check reflection data for default values and set them in writer if missing.

• CE error codes:

  • CE0066: "Entity access is out of date" – unlikely for nanoflows but check access rules if nanoflow accesses entities.
  • CE0433: "Invalid microflow" – if BSON structure is malformed.
  • CE0463: "Widget definition changed" – not applicable (nanoflows have no widgets).

• Qualified name enforcement:

  • MDL must require Module.Nanoflow (no bare names).
  • Visitor already enforces this via qualifiedName rule – verify no implicit module context.

• Microflow/Nanoflow overlap:

  • Since both use Microflows$Microflow $Type, ensure executor correctly sets the Type field to distinguish them.
  • Test: Create both a microflow and nanoflow with same name in different modules – both should coexist.

---

Automated guide via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The enhancement request is understandable but lacks specific details about which MDL operations are needed for nanoflows. Based on the project context and feature matrix, SHOW NANOFLOWS already works (Y), but CREATE, DESCRIBE, DROP, and ALTER are all missing (N). To implement this correctly, I need clarification on:

1. Specific operations required: Do you need CREATE NANOFLOW (to define new nanoflows), DESCRIBE NANOFLOW (to view/export definitions), DROP NANOFLOW, or ALTER NANOFLOW? The phrase "to run logic" suggests CREATE is essential, but DESCRIBE would enable roundtrip workflows.
2. Nanoflow-specific properties: Beyond basic definition (name, parameters, return type), do you need to support properties like folder placement, documentation, or offline capabilities (for mobile)?
3. Activity support: Should MDL support defining nanoflow activities (assignments, loops, calls, etc.) via statements, or just the nanoflow container? The microflow activity set largely applies to nanoflows (with client-side restrictions).
4. Target Mendix version: Nanoflow properties have evolved slightly across versions; knowing your target version helps ensure correct BSON structure.

Without this detail, I'll assume the goal is full CREATE/DESCRIBE support for nanoflows mirroring microflow syntax, as this is the most common gap. If you only need partial support (e.g., just CREATE), please clarify.

Overlap Check

No existing syntax covers nanoflow creation. While:

• SHOW NANOFLOWS works (lists existing nanoflows)
• CALL NANOFLOW Module.Name() works inside microflow/nanoflow bodies
• Nanoflows appear in the catalog and can be queried via SQL

You cannot currently:

• Define new nanoflows via MDL (CREATE NANOFLOW fails with parse error)
• View nanoflow definitions in MDL format (DESCRIBE NANOFLOW unsupported)
• Modify or remove nanoflows via MDL (ALTER/DROP unsupported)

This is a genuine gap in MDL support for the nanoflow document type.

Proposed MDL Syntax

Nanoflows are client-side counterparts to microflows with nearly identical structure. The syntax should mirror microflows using NANOFLOW keyword, following standard MDL patterns (CREATE/ALTER/DROP/SHOW/DESCRIBE). Key properties align with microflows: parameters, return type, folder, documentation.

Design Guidelines Compliance

• ✅ Reads as English: CREATE NANOFLOW MyModule.GetUserName(...) RETURNS String AS $result BEGIN ... END
• ✅ Standard pattern: Uses CREATE/DESCRIBE/DROP/ALTER like other document types
• ✅ Qualified names: Requires Module.NanoflowName (no implicit context)
• ✅ Property format: ( Key: value, ... ) with colon separators
• ✅ LLM-friendly: One example suffices to generate variants (e.g., change return type)
• ✅ Diff-friendly: Adding a property is a one-line diff

Syntax Examples

// Basic nanoflow with parameters and return type
CREATE NANOFLOW MyModule.GetFullName(
    Params: { $first: String, $last: String }
) RETURNS String AS $fullName
BEGIN
  $fullName = $first + ' ' + $last;
  RETURN $fullName;
END;

// Nanoflow with folder and documentation
CREATE NANOFLOW MyModule.CalculateDiscount(
    Params: { $price: Decimal, $rate: Decimal },
    Folder: 'Activities/Utilities',
    Documentation: 'Calculates discount amount from price and rate'
) RETURNS Decimal AS $discount
BEGIN
  $discount = $price * ($rate / 100);
  RETURN $discount;
END;

// Nanoflow calling another nanoflow (client-side only)
CREATE NANOFLOW MyModule.ValidateAddress(
    Params: { $address: String }
) RETURNS Boolean AS $isValid
BEGIN
  $isValid = CALL NANOFLOW MyModule.IsAddressFormatValid(Address: $address);
  IF $isValid THEN
    $isValid = CALL NANOFLOW MyModule.IsAddressNotBlocked(Address: $address);
  END IF;
  RETURN $isValid;
END;

Notes:

• Nanoflow statements (inside BEGIN...END) use the same microflow-compatible syntax (assignments, loops, calls, etc.), but with client-side activity restrictions enforced by Mendix (e.g., no database activities).
• Folder and Documentation properties mirror microflow syntax.
• RETURNS clause is required (nanoflows must return a value, unlike some microflows).
• OFFLINE is not a nanoflow property; nanoflows are inherently client-side and usable offline if the app supports it.

Implementation Roadmap

Follow the full-stack pipeline. Nanoflows share significant structure with microflows, so leverage existing sdk/microflows/ and sdk/mpr/*_microflow.go files where possible.

1. Grammar (mdl/grammar/)

• MDLLexer.g4: Add NANOFLOW token (alphabetical order)
• MDLParser.g4:
  • Add nanoflowStatement alternative to microflowStatement (since nanoflows use same internal statements)
  • Define nanoflowDefinition rule for CREATE/DESCRIBE/etc. (similar to microflowDefinition)
  • Regenerate: make grammar

2. AST (mdl/ast/)

• Create ast_nanoflow.go with:
  • NanoflowStmt struct (mirrors MicroflowStmt but for nanoflow definition)
  • Reuse existing MicroflowBodyStmt for internal statements (nanoflows use same activity set)
  • Add isNanoflowStatement() method

3. Visitor (mdl/visitor/)

• In visitor_nanoflow_statements.go:
  • Implement buildNanoflowStatement() (similar to buildMicroflowStatement())
  • Handle Params, Folder, Documentation, RETURNS clauses
  • Delegate body parsing to existing microflow statement visitor
• Update buildMicroflowStatement() switch to include ctx.NanoflowStatement()

4. SDK Types (sdk/microflows/)

• No new types needed: Nanoflow document type already exists in sdk/microflows/nanoflow.go (inferred from package structure)
• Verify `:

---

Automated guide via OpenRouter — workflow source