feat: ALTER NAVIGATION — incremental menu item operations

[engalar]

Problem

CREATE OR REPLACE NAVIGATION requires a full replacement of the navigation profile. Adding or removing a single menu item means:

1. DESCRIBE NAVIGATION Responsive — read current state
2. Manually edit the full menu tree
3. CREATE OR REPLACE NAVIGATION Responsive ... — write it back

This round-trip is error-prone and verbose for small changes.

Proposed Solution

Add ALTER NAVIGATION with incremental operations, consistent with the existing ALTER PAGE / ALTER ENTITY / ALTER SNIPPET pattern.

Syntax

ALTER NAVIGATION Responsive {
  -- Add a top-level menu item
  ADD MENU ITEM 'Reports' PAGE MyModule.Reports_Overview;

  -- Add into a named sub-menu (multi-level: 'Parent > Child')
  ADD MENU ITEM 'Detail' PAGE MyModule.Reports_Detail IN 'Reports';

  -- Add a sub-menu group
  ADD MENU 'Settings' (
    MENU ITEM 'Users' PAGE Administration.Account_Overview;
    MENU ITEM 'Config' PAGE MyModule.Config_Edit;
  );

  -- Remove by caption (exact match, case-sensitive)
  REMOVE MENU ITEM 'Old Feature';

  -- Remove with path disambiguation
  REMOVE MENU ITEM 'Orders' IN 'Admin';

  -- Change home/login page without touching menu structure
  SET HOME PAGE MyModule.NewHome;
  SET LOGIN PAGE Administration.Login;
}

Path Disambiguation

• IN 'Parent' — appends to the named sub-menu
• IN 'Parent > Child' — multi-level path, separated by >
• No IN — operates at the top level

Error Handling

Condition	Behavior
Target PAGE/MICROFLOW not found	Error (consistent with existing commands)
IN path not found	Error: Menu 'Parent > Child' not found
REMOVE caption not found	Error (no silent failure)
REMOVE caption ambiguous (multiple matches)	Error: suggest using IN to disambiguate
ADD duplicate caption under same parent	Error
Profile name not found	Error (consistent with existing commands)
Multiple operations, failure mid-way	Full rollback, original menu unchanged

Compatibility

• CREATE OR REPLACE NAVIGATION remains unchanged — full-replacement workflow still works
• ALTER NAVIGATION is purely additive to the command set
• References validated by mxcli check --references (PAGE/MICROFLOW targets)

Motivation

When building or updating a Mendix app via MDL scripts, navigation changes are frequent and typically involve one or two items at a time. A fine-grained ALTER NAVIGATION command would make scripts shorter, safer, and easier to review — matching the ergonomics already established by ALTER PAGE.

[github-actions]

Issue Triage

Summary:
The request proposes an ALTER NAVIGATION command to enable incremental menu‑item changes, avoiding the need for a full replace round‑trip.

Checklist for feature request completeness

Required info	Present?	Notes
Use case – why the feature is needed, what problem it solves	✅	Described in the “Problem” and “Motivation” sections.
Proposed syntax or behavior (if applicable)	✅	Detailed syntax, examples, path disambiguation, and error handling are provided.
Mendix version relevance (if version‑specific)	❌	No mention of which Mendix version(s) the feature would apply to or any version‑specific constraints.

Missing information:
Could you please clarify the Mendix version(s) this feature is intended for (e.g., does it work with Mendix 10.x, 9.x, or is it version‑agnostic)? Knowing this will help assess compatibility and prioritize the work.

Thank you for the detailed proposal! Once we have the version relevance, we can move forward.

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Implementation Guide: ALTER NAVIGATION for mxcli

1. Completeness Assessment

The enhancement request provides sufficient detail for implementation:

• Clear problem statement about the round-trip inefficiency of CREATE OR REPLACE NAVIGATION
• Specific proposed syntax with 6 distinct operation types
• Path disambiguation rules using IN notation
• Comprehensive error handling table
• Compatibility notes confirming it won't break existing functionality
• Strong motivation aligning with existing ALTER PAGE/ALTER SNIPPET patterns

No clarifying questions are needed. The request follows established Mendix MDL patterns and provides concrete examples.

2. Overlap Check

No existing overlap - this is a genuine gap in functionality:

From the Feature Matrix in CLAUDE.md:

• Navigation shows: SHOW (Y), DESCRIBE (Y), CREATE (Y), OR MODIFY (-), DROP (-), ALTER (Y)
• The "-" in ALTER column confirms ALTER NAVIGATION is not implemented
• Existing navigation support covers only full replacement (CREATE OR REPLACE) and inspection (SHOW/DESCRIBE)

Existing similar patterns that validate the approach:

• ALTER PAGE / ALTER SNIPPET (implemented per MDL Syntax Quick Reference)
• ALTER ENTITY (implemented)
• ALTER WORKFLOW (implemented)
• All follow the same incremental modification pattern requested for navigation

3. Proposed MDL Syntax Evaluation

The proposed syntax follows MDL design guidelines well:

✅ Reads as English:

• ADD MENU ITEM 'Reports' PAGE MyModule.Reports_Overview reads naturally
• SET HOME PAGE MyModule.NewHome is clear and unambiguous

✅ Follows standard patterns:

• Uses established ADD/REMOVE/SET verbs consistent with ALTER PAGE/ALTER SNIPPET
• Matches CREATE OR REPLACE NAVIGATION structure for familiarity
• Uses same qualified name pattern (Module.Element) for PAGE references

✅ Qualified names:

• All PAGE references use Module.Element format (e.g., MyModule.Reports_Overview)
• No implicit module context - fully explicit as required

✅ Property format:

• Menu groups use ( Key: value, ... ) format with proper indentation
• Example: ADD MENU 'Settings' ( MENU ITEM 'Users' PAGE ...; )

✅ LLM-friendly:

• One example demonstrates all operation types
• Clear, consistent structure that LLMs can generalize from

✅ Diff-friendly:

• Adding one operation is a one-line diff (e.g., adding single ADD MENU ITEM line)
• Removing or modifying operations similarly localized

Minor considerations:

• Path separator > in IN 'Parent > Child' is reasonable but should verify it doesn't conflict with any existing Mendix naming conventions
• Case-sensitive REMOVE behavior should be explicitly documented (matches request)

4. Implementation Roadmap

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

🔹 Grammar (MDLLexer.g4 + MDLParser.g4)

• mdl/grammar/MDLLexer.g4: Add tokens:

  ALTER: A L T E R;
  NAVIGATION: N A V I G A T I O N;
  ADD: A D D;
  MENU: M E N U;
  ITEM: I T E M;
  REMOVE: R E M O V E;
  SET: S E T;
  HOME: H O M E;
  LOGIN: L O G I N;
  IN: I N;
  

• mdl/grammar/MDLParser.g4: Add parser rule:

  navigationStatement
      : ALTER NAVIGATION qualifiedName LBRACE navigationOperation* RBRACE SEMICOLON
      ;
  
  navigationOperation
      : addMenuItemOperation
      | addMenuOperation
      | removeMenuItemOperation
      | setHomePageOperation
      | setLoginPageOperation
      ;
  
  addMenuItemOperation
      : ADD MENU ITEM STRING_LITERAL PAGE qualifiedName (IN pathExpression)? SEMICOLON
      ;
  
  addMenuOperation
      : ADD MENU STRING_LITERAL LPAREN menuItem* RPAREN SEMICOLON
      ;
  
  menuItem
      : MENU ITEM STRING_LITERAL PAGE qualifiedName (IN pathExpression)? SEMICOLON
      ;
  
  removeMenuItemOperation
      : REMOVE MENU ITEM STRING_LITERAL (IN pathExpression)? SEMICOLON
      ;
  
  setHomePageOperation
      : SET HOME PAGE qualifiedName SEMICOLON
      ;
  
  setLoginPageOperation
      : SET LOGIN PAGE qualifiedName SEMICOLON
      ;
  
  pathExpression
      : STRING_LITERAL (GT STRING_LITERAL)*   // Handles 'Parent > Child' syntax
      ;

• Run make grammar to regenerate parser

🔹 AST (mdl/ast/)

• mdl/ast/ast_navigation.go: New file with:

  type AlterNavigationStmt struct {
      Profile  string
      Operations []NavigationOperation
  }
  
  type NavigationOperation interface {
      isNavigationOperation()
  }
  
  type AddMenuItemOperation struct {
      Caption   string
      PageRef   string
      Path      []string // For IN 'Parent > Child' path
  }
  
  type AddMenuOperation struct {
      Caption   string
      Items     []*AddMenuItemOperation
  }
  
  type RemoveMenuItemOperation struct {
      Caption string
      Path    []string
  }
  
  type SetHomePageOperation struct {
      PageRef string
  }
  
  type SetLoginPageOperation struct {
      PageRef string
  }

Vis

---

Automated guide via OpenRouter — workflow source