refactor: define mutation backend interfaces with stub implementations

Add PageMutator, WorkflowMutator, WidgetSerializationBackend interfaces
to mdl/backend/mutation.go for BSON-free handler decoupling. Extract
BSON ID helpers (IDToBsonBinary, BsonBinaryToID, NewIDBsonBinary) to
mdl/bsonutil/ package. Add panic stubs to MprBackend and mock function
fields to MockBackend for all new interface methods.

- Create mdl/bsonutil/bsonutil.go with BSON ID conversion utilities
- Migrate 10 handler files from mpr.IDToBsonBinary to bsonutil.*
- Define PageMutationBackend, WorkflowMutationBackend interfaces
- Define WidgetSerializationBackend with opaque return types
- Add PluggablePropertyContext for domain-typed widget property input

Author: retran

mdl/backend/backend.go

@@ -31,4 +31,7 @@ type FullBackend interface {
 	MetadataBackend
 	WidgetBackend
 	AgentEditorBackend
+	PageMutationBackend
+	WorkflowMutationBackend
+	WidgetSerializationBackend
 }

mdl/backend/mock/backend.go

@@ -258,6 +258,18 @@ type MockBackend struct {
 	FindCustomWidgetTypeFunc     func(widgetID string) (*types.RawCustomWidgetType, error)
 	FindAllCustomWidgetTypesFunc func(widgetID string) ([]*types.RawCustomWidgetType, error)
 
+	// PageMutationBackend
+	OpenPageForMutationFunc func(unitID model.ID) (backend.PageMutator, error)
+
+	// WorkflowMutationBackend
+	OpenWorkflowForMutationFunc func(unitID model.ID) (backend.WorkflowMutator, error)
+
+	// WidgetSerializationBackend
+	SerializeWidgetFunc           func(w pages.Widget) (any, error)
+	SerializeClientActionFunc     func(a pages.ClientAction) (any, error)
+	SerializeDataSourceFunc       func(ds pages.DataSource) (any, error)
+	SerializeWorkflowActivityFunc func(a workflows.WorkflowActivity) (any, error)
+
 	// AgentEditorBackend
 	ListAgentEditorModelsFunc               func() ([]*agenteditor.Model, error)
 	ListAgentEditorKnowledgeBasesFunc       func() ([]*agenteditor.KnowledgeBase, error)

mdl/backend/mock/mock_mutation.go

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mock
+
+import (
+	"github.com/mendixlabs/mxcli/mdl/backend"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/pages"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// ---------------------------------------------------------------------------
+// PageMutationBackend
+// ---------------------------------------------------------------------------
+
+func (m *MockBackend) OpenPageForMutation(unitID model.ID) (backend.PageMutator, error) {
+	if m.OpenPageForMutationFunc != nil {
+		return m.OpenPageForMutationFunc(unitID)
+	}
+	return nil, nil
+}
+
+// ---------------------------------------------------------------------------
+// WorkflowMutationBackend
+// ---------------------------------------------------------------------------
+
+func (m *MockBackend) OpenWorkflowForMutation(unitID model.ID) (backend.WorkflowMutator, error) {
+	if m.OpenWorkflowForMutationFunc != nil {
+		return m.OpenWorkflowForMutationFunc(unitID)
+	}
+	return nil, nil
+}
+
+// ---------------------------------------------------------------------------
+// WidgetSerializationBackend
+// ---------------------------------------------------------------------------
+
+func (m *MockBackend) SerializeWidget(w pages.Widget) (any, error) {
+	if m.SerializeWidgetFunc != nil {
+		return m.SerializeWidgetFunc(w)
+	}
+	return nil, nil
+}
+
+func (m *MockBackend) SerializeClientAction(a pages.ClientAction) (any, error) {
+	if m.SerializeClientActionFunc != nil {
+		return m.SerializeClientActionFunc(a)
+	}
+	return nil, nil
+}
+
+func (m *MockBackend) SerializeDataSource(ds pages.DataSource) (any, error) {
+	if m.SerializeDataSourceFunc != nil {
+		return m.SerializeDataSourceFunc(ds)
+	}
+	return nil, nil
+}
+
+func (m *MockBackend) SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error) {
+	if m.SerializeWorkflowActivityFunc != nil {
+		return m.SerializeWorkflowActivityFunc(a)
+	}
+	return nil, nil
+}

mdl/backend/mpr/backend.go

@@ -724,3 +724,36 @@ func (b *MprBackend) CreateAgentEditorAgent(a *agenteditor.Agent) error {
 func (b *MprBackend) DeleteAgentEditorAgent(id string) error {
 	return b.writer.DeleteAgentEditorAgent(id)
 }
+
+// ---------------------------------------------------------------------------
+// PageMutationBackend
+
+func (b *MprBackend) OpenPageForMutation(unitID model.ID) (backend.PageMutator, error) {
+	panic("MprBackend.OpenPageForMutation not yet implemented")
+}
+
+// ---------------------------------------------------------------------------
+// WorkflowMutationBackend
+
+func (b *MprBackend) OpenWorkflowForMutation(unitID model.ID) (backend.WorkflowMutator, error) {
+	panic("MprBackend.OpenWorkflowForMutation not yet implemented")
+}
+
+// ---------------------------------------------------------------------------
+// WidgetSerializationBackend
+
+func (b *MprBackend) SerializeWidget(w pages.Widget) (any, error) {
+	panic("MprBackend.SerializeWidget not yet implemented")
+}
+
+func (b *MprBackend) SerializeClientAction(a pages.ClientAction) (any, error) {
+	panic("MprBackend.SerializeClientAction not yet implemented")
+}
+
+func (b *MprBackend) SerializeDataSource(ds pages.DataSource) (any, error) {
+	panic("MprBackend.SerializeDataSource not yet implemented")
+}
+
+func (b *MprBackend) SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error) {
+	panic("MprBackend.SerializeWorkflowActivity not yet implemented")
+}

mdl/backend/mutation.go

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package backend
+
+import (
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/pages"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// PageMutator provides fine-grained mutation operations on a single
+// page, layout, or snippet unit. Obtain one via PageMutationBackend.OpenPageForMutation.
+// All methods operate on the in-memory representation; call Save to persist.
+type PageMutator interface {
+	// ContainerType returns "page", "layout", or "snippet".
+	ContainerType() string
+
+	// --- Widget property operations ---
+
+	// SetWidgetProperty sets a simple property on the named widget.
+	// For pluggable widget properties, prop is the Mendix property key
+	// and value is the string representation.
+	SetWidgetProperty(widgetRef string, prop string, value any) error
+
+	// SetWidgetDataSource sets the DataSource on the named widget.
+	SetWidgetDataSource(widgetRef string, ds pages.DataSource) error
+
+	// SetColumnProperty sets a property on a column within a grid widget.
+	SetColumnProperty(gridRef string, columnRef string, prop string, value any) error
+
+	// --- Widget tree operations ---
+
+	// InsertWidget inserts serialized widgets at the given position
+	// relative to the target widget. Position is "before" or "after".
+	InsertWidget(targetWidget string, position string, widgets []pages.Widget) error
+
+	// DropWidget removes widgets by name from the tree.
+	DropWidget(widgetRefs []string) error
+
+	// ReplaceWidget replaces the target widget with the given widgets.
+	ReplaceWidget(targetWidget string, widgets []pages.Widget) error
+
+	// --- Variable operations ---
+
+	// AddVariable adds a local variable to the page/snippet.
+	AddVariable(name, dataType, defaultValue string) error
+
+	// DropVariable removes a local variable by name.
+	DropVariable(name string) error
+
+	// --- Layout operations ---
+
+	// SetLayout changes the layout reference and remaps placeholder parameters.
+	SetLayout(newLayout string, paramMappings map[string]string) error
+
+	// --- Pluggable widget operations ---
+
+	// SetPluggableProperty sets a typed property on a pluggable widget's object.
+	// propKey is the Mendix property key, opName is the operation type
+	// ("attribute", "association", "primitive", "selection", "datasource",
+	// "widgets", "texttemplate", "action", "attributeObjects").
+	// ctx carries the operation-specific values.
+	SetPluggableProperty(widgetRef string, propKey string, opName string, ctx PluggablePropertyContext) error
+
+	// --- Introspection ---
+
+	// EnclosingEntity returns the qualified entity name for the given widget's
+	// data context, or "" if none.
+	EnclosingEntity(widgetRef string) string
+
+	// WidgetScope returns a map of widget name → unit ID for all widgets in the tree.
+	WidgetScope() map[string]model.ID
+
+	// Save persists the mutations to the backend.
+	Save() error
+}
+
+// PluggablePropertyContext carries operation-specific values for
+// SetPluggableProperty. Only fields relevant to the operation are used.
+type PluggablePropertyContext struct {
+	AttributePath  string           // "attribute", "association"
+	AttributePaths []string         // "attributeObjects"
+	AssocPath      string           // "association"
+	EntityName     string           // "association"
+	PrimitiveVal   string           // "primitive"
+	DataSource     pages.DataSource // "datasource"
+	ChildWidgets   []pages.Widget   // "widgets"
+	Action         pages.ClientAction // "action"
+	TextTemplate   string           // "texttemplate"
+	Selection      string           // "selection"
+}
+
+// WorkflowMutator provides fine-grained mutation operations on a single
+// workflow unit. Obtain one via WorkflowMutationBackend.OpenWorkflowForMutation.
+// All methods operate on the in-memory representation; call Save to persist.
+type WorkflowMutator interface {
+	// --- Top-level property operations ---
+
+	// SetProperty sets a workflow-level property (DisplayName, Description,
+	// ExportLevel, DueDate, Parameter, OverviewPage).
+	SetProperty(prop string, value string) error
+
+	// SetPropertyWithEntity sets a workflow-level property that references
+	// an entity (e.g. Parameter).
+	SetPropertyWithEntity(prop string, value string, entity string) error
+
+	// --- Activity operations ---
+
+	// SetActivityProperty sets a property on an activity identified by
+	// caption and optional position index.
+	SetActivityProperty(activityRef string, atPos int, prop string, value string) error
+
+	// InsertAfterActivity inserts new activities after the referenced activity.
+	InsertAfterActivity(activityRef string, atPos int, activities []workflows.WorkflowActivity) error
+
+	// DropActivity removes the referenced activity.
+	DropActivity(activityRef string, atPos int) error
+
+	// ReplaceActivity replaces the referenced activity with new ones.
+	ReplaceActivity(activityRef string, atPos int, activities []workflows.WorkflowActivity) error
+
+	// --- Outcome operations ---
+
+	// InsertOutcome adds a new outcome to the referenced activity.
+	InsertOutcome(activityRef string, atPos int, outcomeName string, activities []workflows.WorkflowActivity) error
+
+	// DropOutcome removes an outcome by name from the referenced activity.
+	DropOutcome(activityRef string, atPos int, outcomeName string) error
+
+	// --- Path operations (parallel split) ---
+
+	InsertPath(activityRef string, atPos int, pathCaption string, activities []workflows.WorkflowActivity) error
+	DropPath(activityRef string, atPos int, pathCaption string) error
+
+	// --- Branch operations (exclusive split) ---
+
+	InsertBranch(activityRef string, atPos int, condition string, activities []workflows.WorkflowActivity) error
+	DropBranch(activityRef string, atPos int, branchName string) error
+
+	// --- Boundary event operations ---
+
+	InsertBoundaryEvent(activityRef string, atPos int, eventType string, delay string, activities []workflows.WorkflowActivity) error
+	DropBoundaryEvent(activityRef string, atPos int) error
+
+	// Save persists the mutations to the backend.
+	Save() error
+}
+
+// PageMutationBackend provides page/layout/snippet mutation capabilities.
+type PageMutationBackend interface {
+	// OpenPageForMutation loads a page, layout, or snippet unit and returns
+	// a mutator for applying changes. Call Save() on the returned mutator
+	// to persist.
+	OpenPageForMutation(unitID model.ID) (PageMutator, error)
+}
+
+// WorkflowMutationBackend provides workflow mutation capabilities.
+type WorkflowMutationBackend interface {
+	// OpenWorkflowForMutation loads a workflow unit and returns a mutator
+	// for applying changes. Call Save() on the returned mutator to persist.
+	OpenWorkflowForMutation(unitID model.ID) (WorkflowMutator, error)
+}
+
+// WidgetSerializationBackend provides widget and activity serialization
+// for CREATE paths where the executor builds domain objects that need
+// to be converted to the storage format.
+type WidgetSerializationBackend interface {
+	// SerializeWidget converts a domain Widget to its storage representation.
+	// The returned value is opaque to the caller; it is only used as input
+	// to mutation operations or passed to the backend for persistence.
+	SerializeWidget(w pages.Widget) (any, error)
+
+	// SerializeClientAction converts a domain ClientAction to storage format.
+	SerializeClientAction(a pages.ClientAction) (any, error)
+
+	// SerializeDataSource converts a domain DataSource to storage format.
+	SerializeDataSource(ds pages.DataSource) (any, error)
+
+	// SerializeWorkflowActivity converts a domain WorkflowActivity to storage format.
+	SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error)
+}

mdl/bsonutil/bsonutil.go

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Package bsonutil provides BSON-aware ID conversion utilities for model elements.
+// It depends on mdl/types (WASM-safe) and the BSON driver (also WASM-safe),
+// but does NOT depend on sdk/mpr (which pulls in SQLite/CGO).
+package bsonutil
+
+import (
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"go.mongodb.org/mongo-driver/bson/primitive"
+)
+
+// IDToBsonBinary converts a hex UUID string to a BSON binary value.
+func IDToBsonBinary(id string) primitive.Binary {
+	blob := types.UUIDToBlob(id)
+	if blob == nil || len(blob) != 16 {
+		blob = types.UUIDToBlob(types.GenerateID())
+	}
+	return primitive.Binary{
+		Subtype: 0x00,
+		Data:    blob,
+	}
+}
+
+// BsonBinaryToID converts a BSON binary value to a hex UUID string.
+func BsonBinaryToID(bin primitive.Binary) string {
+	return types.BlobToUUID(bin.Data)
+}
+
+// NewIDBsonBinary generates a new unique ID and returns it as a BSON binary value.
+func NewIDBsonBinary() primitive.Binary {
+	return IDToBsonBinary(types.GenerateID())
+}