feat: add MOVE FOLDER command for reorganizing folders

Syntax: MOVE FOLDER Module.FolderName TO FOLDER 'path' [IN Module]
Uses the same qualified name pattern as document moves. Double quotes
for nested paths: MOVE FOLDER Module."Parent/Child" TO TargetModule.

Includes grammar, AST, visitor, executor, writer, docs, skills,
help topics, and examples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

.claude/skills/mendix/organize-project.md

@@ -202,6 +202,24 @@ MOVE ENTITY CRM.Customer TO CustomerModule;
 MOVE ENUMERATION CRM.OrderStatus TO SharedModule;
 ```
 
+## Moving Folders
+
+Use `MOVE FOLDER` to reorganize folders. Syntax matches document moves: `Module.FolderName`.
+
+```sql
+-- Move a folder into another folder
+MOVE FOLDER MyModule.Resources TO FOLDER 'Archive';
+
+-- Move a nested folder (use double quotes for paths with /)
+MOVE FOLDER MyModule."Orders/Archive" TO MyModule;
+
+-- Move a folder to a different module
+MOVE FOLDER MyModule.SharedWidgets TO CommonModule;
+
+-- Move a folder into a folder in another module
+MOVE FOLDER MyModule.Templates TO FOLDER 'Shared' IN CommonModule;
+```
+
 ## Deleting Folders
 
 Use `DROP FOLDER` to remove empty folders. The folder must not contain any documents or sub-folders.

cmd/mxcli/help_topics/move.txt

@@ -57,6 +57,17 @@ EXAMPLES
   SHOW IMPACT OF OldModule.CustomerPage;
   MOVE PAGE OldModule.CustomerPage TO NewModule;
 
+MOVE FOLDER
+-----------
+
+Move a folder to another location:
+  MOVE FOLDER Module.FolderName TO FOLDER 'TargetPath';
+  MOVE FOLDER Module.FolderName TO TargetModule;
+  MOVE FOLDER Module.FolderName TO FOLDER 'TargetPath' IN TargetModule;
+
+For nested folder paths, use double quotes:
+  MOVE FOLDER Module."Parent/Child" TO TargetModule;
+
 DROP FOLDER
 -----------
 

docs-site/src/SUMMARY.md

@@ -262,6 +262,7 @@
   - [CREATE FOLDER](reference/organization/create-folder.md)
   - [DROP FOLDER](reference/organization/drop-folder.md)
   - [MOVE](reference/organization/move.md)
+  - [MOVE FOLDER](reference/organization/move-folder.md)
 - [Session Statements](reference/session/README.md)
   - [SET](reference/session/set.md)
   - [SHOW STATUS](reference/session/show-status.md)

docs-site/src/reference/organization/README.md

@@ -8,3 +8,4 @@ Statements for organizing project structure: creating modules and folders, and m
 | [CREATE FOLDER](create-folder.md) | Create a folder within a module for organizing documents |
 | [DROP FOLDER](drop-folder.md) | Drop an empty folder from a module |
 | [MOVE](move.md) | Move a document to a different module or folder |
+| [MOVE FOLDER](move-folder.md) | Move a folder to another location or module |

docs-site/src/reference/organization/drop-folder.md

@@ -53,4 +53,4 @@ DROP FOLDER 'Processing' IN MyModule;
 
 ## See Also
 
-[CREATE FOLDER](create-folder.md), [CREATE MODULE](create-module.md), [MOVE](move.md)
+[CREATE FOLDER](create-folder.md), [CREATE MODULE](create-module.md), [MOVE](move.md), [MOVE FOLDER](move-folder.md)

docs-site/src/reference/organization/move-folder.md

@@ -0,0 +1,56 @@
+# MOVE FOLDER
+
+## Synopsis
+
+    MOVE FOLDER qualified_name TO FOLDER 'folder_path';
+    MOVE FOLDER qualified_name TO FOLDER 'folder_path' IN module_name;
+    MOVE FOLDER qualified_name TO module_name;
+
+## Description
+
+Moves a folder (and all its contents) to a different location: another folder within the same module, a folder in a different module, or a module root. The folder's contents (documents and sub-folders) move with it.
+
+The source folder is identified using the standard qualified name syntax: `Module.FolderName`. For nested folder paths containing `/`, use double quotes: `Module."Parent/Child"`.
+
+Target folders are created automatically if they don't exist.
+
+## Parameters
+
+**qualified_name**
+: The source folder in `Module.FolderName` format. Use double quotes for paths with `/` or special characters.
+
+**folder_path**
+: The target folder path. Use `/` for nested folders.
+
+**module_name**
+: The target module name (for cross-module moves).
+
+## Examples
+
+### Move a folder into another folder
+
+```sql
+MOVE FOLDER MyModule.Resources TO FOLDER 'Archive';
+```
+
+### Move a nested folder to module root
+
+```sql
+MOVE FOLDER MyModule."Orders/Archive" TO MyModule;
+```
+
+### Move a folder to a different module
+
+```sql
+MOVE FOLDER MyModule.SharedWidgets TO CommonModule;
+```
+
+### Move a folder into a folder in another module
+
+```sql
+MOVE FOLDER MyModule.Templates TO FOLDER 'Shared/Templates' IN CommonModule;
+```
+
+## See Also
+
+[CREATE FOLDER](create-folder.md), [DROP FOLDER](drop-folder.md), [MOVE](move.md)

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -179,6 +179,7 @@ AUTHENTICATION Basic, Session
 | Microflow folder | `FOLDER 'path'` (before BEGIN) | `CREATE MICROFLOW ... FOLDER 'ACT' BEGIN ... END;` |
 | Page folder | `Folder: 'path'` (in properties) | `CREATE PAGE ... (Folder: 'Pages/Detail') { ... }` |
 | Drop folder | `DROP FOLDER 'path' IN Module;` | Folder must be empty |
+| Move folder | `MOVE FOLDER Module.FolderName TO FOLDER 'path';` | Target folders auto-created |
 | Move to folder | `MOVE PAGE\|MICROFLOW\|SNIPPET\|NANOFLOW\|ENUMERATION Module.Name TO FOLDER 'path';` | Folders created automatically |
 | Move to module root | `MOVE PAGE Module.Name TO Module;` | Removes from folder |
 | Move across modules | `MOVE PAGE Old.Name TO NewModule;` | **Breaks by-name references** — use `SHOW IMPACT OF` first |

mdl-examples/doctype-tests/18-folder-examples.mdl

@@ -53,6 +53,20 @@ MOVE MICROFLOW FolderTest.ACT_Process TO FOLDER 'Resources';
 MOVE MICROFLOW FolderTest.ACT_Archive TO FolderTest;
 /
 
+-- MARK: - Move Folders
+
+/**
+ * Level 2.3: Move a folder into another folder
+ */
+MOVE FOLDER FolderTest.Resources TO FOLDER 'Processing';
+/
+
+/**
+ * Level 2.4: Move a nested folder to module root (use quotes for paths with /)
+ */
+MOVE FOLDER FolderTest."Processing/Resources" TO FolderTest;
+/
+
 -- MARK: - Drop Folders
 
 /**

mdl/ast/ast_enumeration.go

@@ -35,6 +35,15 @@ type DropFolderStmt struct {
 
 func (s *DropFolderStmt) isStatement() {}
 
+// MoveFolderStmt represents: MOVE FOLDER Module.FolderName TO ...
+type MoveFolderStmt struct {
+	Name         QualifiedName // Source: Module.FolderName (Name may be "Parent/Child" for nested)
+	TargetFolder string        // Target folder path (empty = module root)
+	TargetModule string        // Target module name (empty = same module)
+}
+
+func (s *MoveFolderStmt) isStatement() {}
+
 // CreateEnumerationStmt represents: CREATE ENUMERATION Module.Name (values) COMMENT '...'
 type CreateEnumerationStmt struct {
 	Name           QualifiedName

mdl/executor/cmd_folders.go

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-// Package executor - DROP FOLDER command
+// Package executor - DROP/MOVE FOLDER commands
 package executor
 
 import (
@@ -9,30 +9,13 @@ import (
 
 	"github.com/mendixlabs/mxcli/mdl/ast"
 	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/mpr"
 )
 
-// execDropFolder handles DROP FOLDER 'path' IN Module statements.
-// The folder must be empty (no child documents or sub-folders).
-func (e *Executor) execDropFolder(s *ast.DropFolderStmt) error {
-	if e.writer == nil {
-		return fmt.Errorf("not connected to a project")
-	}
-
-	// Find the module
-	module, err := e.findModule(s.Module)
-	if err != nil {
-		return fmt.Errorf("module not found: %s", s.Module)
-	}
-
-	// List all folders
-	folders, err := e.reader.ListFolders()
-	if err != nil {
-		return fmt.Errorf("failed to list folders: %w", err)
-	}
-
-	// Walk the folder path to find the target folder
-	parts := strings.Split(s.FolderPath, "/")
-	currentContainerID := module.ID
+// findFolderByPath walks a folder path under a module and returns the folder ID.
+func (e *Executor) findFolderByPath(moduleID model.ID, folderPath string, folders []*mpr.FolderInfo) (model.ID, error) {
+	parts := strings.Split(folderPath, "/")
+	currentContainerID := moduleID
 
 	var targetFolderID model.ID
 	for i, part := range parts {
@@ -53,20 +36,104 @@ func (e *Executor) execDropFolder(s *ast.DropFolderStmt) error {
 		}
 
 		if !found {
-			return fmt.Errorf("folder not found: '%s' in %s", s.FolderPath, s.Module)
+			return "", fmt.Errorf("folder not found: '%s'", folderPath)
 		}
 	}
 
 	if targetFolderID == "" {
-		return fmt.Errorf("folder not found: '%s' in %s", s.FolderPath, s.Module)
+		return "", fmt.Errorf("folder not found: '%s'", folderPath)
+	}
+
+	return targetFolderID, nil
+}
+
+// execDropFolder handles DROP FOLDER 'path' IN Module statements.
+// The folder must be empty (no child documents or sub-folders).
+func (e *Executor) execDropFolder(s *ast.DropFolderStmt) error {
+	if e.writer == nil {
+		return fmt.Errorf("not connected to a project")
+	}
+
+	module, err := e.findModule(s.Module)
+	if err != nil {
+		return fmt.Errorf("module not found: %s", s.Module)
+	}
+
+	folders, err := e.reader.ListFolders()
+	if err != nil {
+		return fmt.Errorf("failed to list folders: %w", err)
+	}
+
+	folderID, err := e.findFolderByPath(module.ID, s.FolderPath, folders)
+	if err != nil {
+		return fmt.Errorf("%w in %s", err, s.Module)
 	}
 
-	// Delete the folder (writer checks if empty)
-	if err := e.writer.DeleteFolder(targetFolderID); err != nil {
+	if err := e.writer.DeleteFolder(folderID); err != nil {
 		return fmt.Errorf("failed to delete folder '%s': %w", s.FolderPath, err)
 	}
 
 	e.invalidateHierarchy()
 	fmt.Fprintf(e.output, "Dropped folder: '%s' in %s\n", s.FolderPath, s.Module)
 	return nil
 }
+
+// execMoveFolder handles MOVE FOLDER Module.FolderName TO ... statements.
+func (e *Executor) execMoveFolder(s *ast.MoveFolderStmt) error {
+	if e.writer == nil {
+		return fmt.Errorf("not connected to a project")
+	}
+
+	// Find the source module
+	sourceModule, err := e.findModule(s.Name.Module)
+	if err != nil {
+		return fmt.Errorf("source module not found: %s", s.Name.Module)
+	}
+
+	// Find the source folder
+	folders, err := e.reader.ListFolders()
+	if err != nil {
+		return fmt.Errorf("failed to list folders: %w", err)
+	}
+
+	folderID, err := e.findFolderByPath(sourceModule.ID, s.Name.Name, folders)
+	if err != nil {
+		return fmt.Errorf("%w in %s", err, s.Name.Module)
+	}
+
+	// Determine target module
+	var targetModule *model.Module
+	if s.TargetModule != "" {
+		targetModule, err = e.findModule(s.TargetModule)
+		if err != nil {
+			return fmt.Errorf("target module not found: %s", s.TargetModule)
+		}
+	} else {
+		targetModule = sourceModule
+	}
+
+	// Resolve target container
+	var targetContainerID model.ID
+	if s.TargetFolder != "" {
+		targetContainerID, err = e.resolveFolder(targetModule.ID, s.TargetFolder)
+		if err != nil {
+			return fmt.Errorf("failed to resolve target folder: %w", err)
+		}
+	} else {
+		targetContainerID = targetModule.ID
+	}
+
+	// Move the folder
+	if err := e.writer.MoveFolder(folderID, targetContainerID); err != nil {
+		return fmt.Errorf("failed to move folder: %w", err)
+	}
+
+	e.invalidateHierarchy()
+
+	target := targetModule.Name
+	if s.TargetFolder != "" {
+		target += "/" + s.TargetFolder
+	}
+	fmt.Fprintf(e.output, "Moved folder %s to %s\n", s.Name.String(), target)
+	return nil
+}