Merge pull request #239 from retran/feature/code-quality-polish

refactor: code quality — deterministic output, doc comments, naming

Author: ako

.gitignore

@@ -58,3 +58,4 @@ grammardoc
 
 # Snap tool binary (used for BSON fixture generation)
 snap-bson
+.playwright-cli/

mdl/ast/ast_agenteditor.go

@@ -16,16 +16,16 @@ package ast
 //	  [, DeepLinkURL: '...']
 //	);
 type CreateModelStmt struct {
-	Name             QualifiedName
-	Documentation    string
-	Provider         string         // "MxCloudGenAI" by default
-	Key              *QualifiedName // qualified name of the String constant holding the Portal key
-	DisplayName      string         // optional Portal-populated metadata
-	KeyName          string         // optional Portal-populated metadata
-	KeyID            string         // optional Portal-populated metadata
-	Environment      string         // optional Portal-populated metadata
-	ResourceName     string         // optional Portal-populated metadata
-	DeepLinkURL      string         // optional Portal-populated metadata
+	Name          QualifiedName
+	Documentation string
+	Provider      string         // "MxCloudGenAI" by default
+	Key           *QualifiedName // qualified name of the String constant holding the Portal key
+	DisplayName   string         // optional Portal-populated metadata
+	KeyName       string         // optional Portal-populated metadata
+	KeyID         string         // optional Portal-populated metadata
+	Environment   string         // optional Portal-populated metadata
+	ResourceName  string         // optional Portal-populated metadata
+	DeepLinkURL   string         // optional Portal-populated metadata
 }
 
 func (s *CreateModelStmt) isStatement() {}
@@ -93,21 +93,21 @@ func (s *DropKnowledgeBaseStmt) isStatement() {}
 
 // CreateAgentStmt represents CREATE AGENT Module.Name (...) [{ body }].
 type CreateAgentStmt struct {
-	Name         QualifiedName
+	Name          QualifiedName
 	Documentation string
-	UsageType    string // "Task" or "Conversational"
-	Description  string
-	Model        *QualifiedName // reference to a Model document
-	Entity       *QualifiedName // reference to a domain entity
-	MaxTokens    *int
-	ToolChoice   string
-	Temperature  *float64
-	TopP         *float64
-	SystemPrompt string
-	UserPrompt   string
-	Variables    []AgentVarDef
-	Tools        []AgentToolDef
-	KBTools      []AgentKBToolDef
+	UsageType     string // "Task" or "Conversational"
+	Description   string
+	Model         *QualifiedName // reference to a Model document
+	Entity        *QualifiedName // reference to a domain entity
+	MaxTokens     *int
+	ToolChoice    string
+	Temperature   *float64
+	TopP          *float64
+	SystemPrompt  string
+	UserPrompt    string
+	Variables     []AgentVarDef
+	Tools         []AgentToolDef
+	KBTools       []AgentKBToolDef
 }
 
 func (s *CreateAgentStmt) isStatement() {}
@@ -136,10 +136,10 @@ type AgentToolDef struct {
 
 // AgentKBToolDef represents a KNOWLEDGE BASE block in CREATE AGENT body.
 type AgentKBToolDef struct {
-	Name                 string // per-agent identifier
-	Source               *QualifiedName
-	Collection           string
-	MaxResults           int
-	Description          string
-	Enabled              bool
+	Name        string // per-agent identifier
+	Source      *QualifiedName
+	Collection  string
+	MaxResults  int
+	Description string
+	Enabled     bool
 }

mdl/backend/connection.go

@@ -25,24 +25,36 @@ type ConnectionBackend interface {
 	// ProjectVersion returns the Mendix project version.
 	ProjectVersion() *types.ProjectVersion
 	// GetMendixVersion returns the Mendix version string.
+	// NOTE: uses Get prefix unlike Version()/ProjectVersion() for historical SDK compatibility.
 	GetMendixVersion() (string, error)
 }
 
 // ModuleBackend provides module-level operations.
 type ModuleBackend interface {
+	// ListModules returns all modules in the project.
 	ListModules() ([]*model.Module, error)
+	// GetModule returns a module by ID.
 	GetModule(id model.ID) (*model.Module, error)
+	// GetModuleByName returns a module by name.
 	GetModuleByName(name string) (*model.Module, error)
+	// CreateModule adds a new module to the project.
 	CreateModule(module *model.Module) error
+	// UpdateModule persists changes to an existing module.
 	UpdateModule(module *model.Module) error
+	// DeleteModule removes a module by ID.
 	DeleteModule(id model.ID) error
+	// DeleteModuleWithCleanup removes a module and cleans up associated documents.
 	DeleteModuleWithCleanup(id model.ID, moduleName string) error
 }
 
 // FolderBackend provides folder operations.
 type FolderBackend interface {
+	// ListFolders returns all folders in the project.
 	ListFolders() ([]*types.FolderInfo, error)
+	// CreateFolder adds a new folder.
 	CreateFolder(folder *model.Folder) error
+	// DeleteFolder removes a folder by ID.
 	DeleteFolder(id model.ID) error
+	// MoveFolder moves a folder to a new container.
 	MoveFolder(id model.ID, newContainerID model.ID) error
 }

mdl/backend/infrastructure.go

@@ -16,14 +16,16 @@ type RenameBackend interface {
 }
 
 // RawUnitBackend provides low-level unit access for operations that
-// manipulate raw BSON (e.g. widget patching, alter page/workflow).
+// manipulate raw unit contents (e.g. widget patching, alter page/workflow).
 type RawUnitBackend interface {
 	GetRawUnit(id model.ID) (map[string]any, error)
 	GetRawUnitBytes(id model.ID) ([]byte, error)
 	ListRawUnitsByType(typePrefix string) ([]*types.RawUnit, error)
 	ListRawUnits(objectType string) ([]*types.RawUnitInfo, error)
 	GetRawUnitByName(objectType, qualifiedName string) (*types.RawUnitInfo, error)
 	GetRawMicroflowByName(qualifiedName string) ([]byte, error)
+	// UpdateRawUnit replaces the contents of a unit by ID.
+	// Takes string (not model.ID) to match the SDK writer layer convention.
 	UpdateRawUnit(unitID string, contents []byte) error
 }
 
@@ -45,6 +47,7 @@ type WidgetBackend interface {
 }
 
 // AgentEditorBackend provides agent editor document operations.
+// Delete methods take string IDs to match the SDK writer layer convention.
 type AgentEditorBackend interface {
 	ListAgentEditorModels() ([]*agenteditor.Model, error)
 	ListAgentEditorKnowledgeBases() ([]*agenteditor.KnowledgeBase, error)
@@ -59,3 +62,22 @@ type AgentEditorBackend interface {
 	CreateAgentEditorAgent(a *agenteditor.Agent) error
 	DeleteAgentEditorAgent(id string) error
 }
+
+// SettingsBackend provides project settings operations.
+type SettingsBackend interface {
+	GetProjectSettings() (*model.ProjectSettings, error)
+	UpdateProjectSettings(ps *model.ProjectSettings) error
+}
+
+// ImageBackend provides image collection operations.
+type ImageBackend interface {
+	ListImageCollections() ([]*types.ImageCollection, error)
+	CreateImageCollection(ic *types.ImageCollection) error
+	DeleteImageCollection(id string) error
+}
+
+// ScheduledEventBackend provides scheduled event operations.
+type ScheduledEventBackend interface {
+	ListScheduledEvents() ([]*model.ScheduledEvent, error)
+	GetScheduledEvent(id model.ID) (*model.ScheduledEvent, error)
+}

mdl/backend/mapping.go

@@ -26,5 +26,7 @@ type MappingBackend interface {
 	ListJsonStructures() ([]*types.JsonStructure, error)
 	GetJsonStructureByQualifiedName(moduleName, name string) (*types.JsonStructure, error)
 	CreateJsonStructure(js *types.JsonStructure) error
+	// DeleteJsonStructure removes a JSON structure by ID.
+	// Takes string (not model.ID) to match the SDK writer layer convention.
 	DeleteJsonStructure(id string) error
 }

mdl/backend/microflow.go

@@ -17,7 +17,7 @@ type MicroflowBackend interface {
 	MoveMicroflow(mf *microflows.Microflow) error
 
 	// ParseMicroflowFromRaw builds a Microflow from an already-unmarshalled
-	// BSON map. Used by diff-local and other callers that have raw map data.
+	// map. Used by diff-local and other callers that have raw map data.
 	ParseMicroflowFromRaw(raw map[string]any, unitID, containerID model.ID) *microflows.Microflow
 
 	ListNanoflows() ([]*microflows.Nanoflow, error)

mdl/backend/mock/backend.go

@@ -7,12 +7,12 @@ package mock
 
 import (
 	"github.com/mendixlabs/mxcli/mdl/backend"
+	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/sdk/agenteditor"
 	"github.com/mendixlabs/mxcli/sdk/domainmodel"
 	"github.com/mendixlabs/mxcli/sdk/javaactions"
 	"github.com/mendixlabs/mxcli/sdk/microflows"
-	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/sdk/pages"
 	"github.com/mendixlabs/mxcli/sdk/security"
 	"github.com/mendixlabs/mxcli/sdk/workflows"
@@ -75,19 +75,19 @@ type MockBackend struct {
 	UpdateEnumerationRefsInAllDomainModelsFunc func(oldQualifiedName, newQualifiedName string) error
 
 	// MicroflowBackend
-	ListMicroflowsFunc  func() ([]*microflows.Microflow, error)
-	GetMicroflowFunc    func(id model.ID) (*microflows.Microflow, error)
-	CreateMicroflowFunc func(mf *microflows.Microflow) error
-	UpdateMicroflowFunc func(mf *microflows.Microflow) error
-	DeleteMicroflowFunc func(id model.ID) error
-	MoveMicroflowFunc          func(mf *microflows.Microflow) error
-	ParseMicroflowFromRawFunc  func(raw map[string]any, unitID, containerID model.ID) *microflows.Microflow
-	ListNanoflowsFunc   func() ([]*microflows.Nanoflow, error)
-	GetNanoflowFunc     func(id model.ID) (*microflows.Nanoflow, error)
-	CreateNanoflowFunc  func(nf *microflows.Nanoflow) error
-	UpdateNanoflowFunc  func(nf *microflows.Nanoflow) error
-	DeleteNanoflowFunc  func(id model.ID) error
-	MoveNanoflowFunc    func(nf *microflows.Nanoflow) error
+	ListMicroflowsFunc        func() ([]*microflows.Microflow, error)
+	GetMicroflowFunc          func(id model.ID) (*microflows.Microflow, error)
+	CreateMicroflowFunc       func(mf *microflows.Microflow) error
+	UpdateMicroflowFunc       func(mf *microflows.Microflow) error
+	DeleteMicroflowFunc       func(id model.ID) error
+	MoveMicroflowFunc         func(mf *microflows.Microflow) error
+	ParseMicroflowFromRawFunc func(raw map[string]any, unitID, containerID model.ID) *microflows.Microflow
+	ListNanoflowsFunc         func() ([]*microflows.Nanoflow, error)
+	GetNanoflowFunc           func(id model.ID) (*microflows.Nanoflow, error)
+	CreateNanoflowFunc        func(nf *microflows.Nanoflow) error
+	UpdateNanoflowFunc        func(nf *microflows.Nanoflow) error
+	DeleteNanoflowFunc        func(id model.ID) error
+	MoveNanoflowFunc          func(nf *microflows.Nanoflow) error
 
 	// PageBackend
 	ListPagesFunc          func() ([]*pages.Page, error)

mdl/backend/mock/mock_infrastructure.go

@@ -3,9 +3,9 @@
 package mock
 
 import (
+	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/sdk/agenteditor"
-	"github.com/mendixlabs/mxcli/mdl/types"
 )
 
 // ---------------------------------------------------------------------------

mdl/backend/mock/mock_java.go

@@ -3,9 +3,9 @@
 package mock
 
 import (
+	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/sdk/javaactions"
-	"github.com/mendixlabs/mxcli/mdl/types"
 )
 
 func (m *MockBackend) ListJavaActions() ([]*types.JavaAction, error) {

mdl/backend/mock/mock_mapping.go

@@ -3,8 +3,8 @@
 package mock
 
 import (
-	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/model"
 )
 
 func (m *MockBackend) ListImportMappings() ([]*model.ImportMapping, error) {