MachinaXX.MakerCLI 2.1.2

MakerCLI

A powerful command-line tool for model-driven code generation and automated deployment. MakerCLI orchestrates the building of code artifacts from models and templates, then publishes the generated files to configured destinations. Updated for MachinaXX.Maker Phase 1 compatibility with async generation and enhanced performance.

Features

• Modern Async Code Generation: Generate code and artifacts using MachinaXX.Maker Phase 1 async API
• Parallel Processing: Leverage multi-core CPUs for faster code generation with configurable parallelism
• Enhanced Error Handling: Functional error handling with Result types and structured error information
• Model Validation & JSON Export: Validate XML models and export parsed structures as JSON
• Template Validation: Validate template syntax for Scriban, Razor, and XSLT templates without requiring a model
• Hierarchical Configuration: Merge root and model-specific settings for flexible project management
• Automated Publishing: Deploy generated files to multiple destinations with parallel processing
• Resilient Operations: Built-in retry logic with exponential backoff for reliable file operations
• Cross-Platform Support: Works on Windows and Linux with platform-specific configurations
• Comprehensive Logging: Detailed logging throughout the build and publish pipeline
• Cancellation Support: Responsive cancellation handling throughout the entire pipeline

Quick Start

Prerequisites

• .NET 8.0 or later
• MachinaXX.Maker library (Phase 1 compatible)

Installation

As a .NET Global Tool (Recommended)

# Install globally
dotnet tool install --global MachinaXX.MakerCLI

# Update to latest version
dotnet tool update --global MachinaXX.MakerCLI

# Verify installation
makercli --help

From Source

git clone https://github.com/Machina-XX/MakerCLI.git
cd MakerCLI
dotnet build

Basic Usage

When Installed as Global Tool

# Build a model
makercli --modelname=MyModel

# Build with custom paths
makercli --modelname=MyModel --modelpath=/custom/models --templatepath=/custom/templates

# Build and publish
makercli --modelname=MyModel --publish=true

# Use different folder name
makercli --modelname=MyModel --foldername=CustomFolder

# Validate model and export JSON
makercli --modelname=MyModel --validate=true

# Only validate, don't build (exports JSON)
makercli --modelname=MyModel --validate=only

# Validate templates only (no model required)
makercli --validate-templates=true

# Validate templates with custom path
makercli --validate-templates=true --templatepath=/custom/templates

When Running from Source

# Build a model
dotnet run -- --modelname=MyModel

# Build with custom paths
dotnet run -- --modelname=MyModel --modelpath=/custom/models --templatepath=/custom/templates

# Build and publish
dotnet run -- --modelname=MyModel --publish=true

# Use different folder name
dotnet run -- --modelname=MyModel --foldername=CustomFolder

# Validate model and export JSON
dotnet run -- --modelname=MyModel --validate=true

# Only validate, don't build (exports JSON)
dotnet run -- --modelname=MyModel --validate=only

# Validate templates only (no model required)
dotnet run -- --validate-templates=true

# Validate templates with custom path
dotnet run -- --validate-templates=true --templatepath=/custom/templates

Uninstalling

# Uninstall the global tool
dotnet tool uninstall --global MachinaXX.MakerCLI

Configuration

MakerCLI uses a two-tier configuration system with JSON files:

Application Settings (appsettings.json)

{
  "ApplicationSettings": {
    "ModelPath": "E:\\MechanaX\\MakerModels\\Model",
    "TemplatePath": "E:\\MechanaX\\MakerTemplates",
    "MakerRoot": "https://maker.xxboom.co.za/Maker.asmx/",
    "WriteSettings": true
  }
}

Model Configuration Structure

ModelPath/
├── config.json                 # Root configuration
└── [ModelName]/
    ├── config.json             # Model-specific overrides
    └── settings.json           # Generated merged settings (optional)

Configuration Schema

Root Configuration (config.json)

{
  "Modelname": "MyModel",
  "Config": {
    "AccessLabel": "access-key",
    "PassportLabel": "passport-key",
    "ApiLabel": "api-key"
  },
  "SourcePaths": [
    {
      "Name": "root",
      "Parent": null,
      "Folder": "C:\\Projects"
    },
    {
      "Name": "output",
      "Parent": "root",
      "Folder": "Generated"
    }
  ],
  "DestinationPaths": [
    {
      "Name": "deploy",
      "Parent": null,
      "Folder": "C:\\Deployment"
    }
  ],
  "Sections": [
    {
      "Name": "WebFiles",
      "SourcePath": "output",
      "DestinationPath": "deploy",
      "Filespec": "*.html"
    }
  ]
}

Architecture

Services

• IBuildService: Handles model building and code generation using async MachinaXX.Maker API
• IPublishService: Manages file deployment with retry logic
• BuildOrPublishService: Main orchestration service (hosted service) with cancellation support

Configuration Management

• SettingsReader: Loads and merges hierarchical configurations
• SettingsDataExtensions: Resolves complex path hierarchies
• AutoMapper Integration: Custom profiles for configuration merging
• Result Extensions: Seamless integration between Maker and MakerCLI Result types

Key Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Command Line   │───▶│ BuildOrPublish   │───▶│   Build/Publish │
│   Arguments     │    │    Service       │    │    Services     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────▼──────┐
                       │  Settings   │
                       │   Reader    │
                       └─────────────┘

Command Line Arguments

Argument	Required	Description	Default
modelname	Yes	Name of the model to build	-
foldername	No	Folder name for the model	Same as modelname
modelpath	No	Path to model directory	From appsettings.json
templatepath	No	Path to template directory	From appsettings.json
publish	No	Whether to publish after build	false
validate	No	Model validation mode: false, true, only	false
validate-templates	No	Validate template syntax only (no model required)	false

Path Resolution

MakerCLI supports hierarchical path definitions where paths can reference parent paths:

{
  "SourcePaths": [
    {
      "Name": "projects",
      "Parent": null,
      "Folder": "C:\\Projects"
    },
    {
      "Name": "current",
      "Parent": "projects",
      "Folder": "MyApp"
    },
    {
      "Name": "output",
      "Parent": "current", 
      "Folder": "bin\\Release"
    }
  ]
}

This resolves output to: C:\\Projects\\MyApp\\bin\\Release

Publishing

The publish system supports multiple sections with different file specifications:

• Parallel Processing: Sections are published concurrently
• File Pattern Matching: Use standard file specs (*.dll, *.config, etc.)
• Automatic Directory Creation: Destination directories are created as needed
• Retry Logic: Failed file operations are retried with exponential backoff

Model Validation & JSON Export

MakerCLI includes comprehensive model validation and JSON export capabilities:

Validation Modes

• --validate=false (default): Skip validation entirely
• --validate=true: Validate model before build, proceed only if valid, export JSON
• --validate=only: Validate model and export JSON, skip build process

JSON Export Feature

When validation is enabled, MakerCLI automatically exports the parsed model structure:

• Trigger: Activated with --validate=true or --validate=only
• Output: {ModelName}.json file in the configured output directory
• Content: Clean, structured JSON representation of the parsed MakerXModel object
• Format: Indented JSON with camelCase property naming
• Behavior:
  • Exports successfully parsed models (even with validation warnings)
  • Skips export only when model parsing fails
  • Creates output directory if it doesn't exist

Example Usage

# Validate and build (creates MyModel.json in output path)
dotnet run -- --modelname=MyModel --validate=true

# Only validate and export JSON (no build)
dotnet run -- --modelname=MyModel --validate=only

# Custom output path for JSON export
dotnet run -- --modelname=MyModel --validate=only --modelpath=/custom/models

The exported JSON contains the complete model structure including database schema, table definitions, column metadata, and configuration settings.

Template Validation

MakerCLI provides standalone template validation to verify template syntax without requiring a model. This is useful for:

• Development: Catch syntax errors early in template development
• CI/CD Integration: Validate templates as part of your build pipeline
• Quality Assurance: Ensure all templates are syntactically correct before deployment

Supported Template Engines

• Scriban (.scriban, .sbn)
• Razor (.cshtml)
• XSLT (.xslt, .xsl)

Features

• Multi-engine validation: Automatically detects and validates each template type
• Include path validation: Validates {{include}} paths in Scriban templates
• Detailed error reporting: Shows line/column numbers for syntax errors
• Summary report: Displays counts of valid and invalid templates
• No model required: Can run independently without specifying --modelname

Usage Examples

# Validate all templates in default template directory
dotnet run -- --validate-templates=true

# Validate templates with custom path
dotnet run -- --validate-templates=true --templatepath=/path/to/templates

# Use in CI/CD pipeline
dotnet run -- --validate-templates=true --templatepath=./templates || exit 1

Sample Output

═══════════════════════════════════════════════════════════
  Template Validation Summary
═══════════════════════════════════════════════════════════
  Total Templates: 15
  Valid:           14
  Invalid:         1
═══════════════════════════════════════════════════════════

❌ Invalid Templates:

  File: model-details.scriban
  Engine: Scriban
  Status: ❌ Invalid
  Error: Unexpected token 'end' at line 23, column 5

Error Handling

• Comprehensive logging at all levels
• Graceful handling of missing files and directories
• Retry mechanisms for file access conflicts
• Detailed error messages with context
• Enhanced with Result types: Functional error handling with structured error information from MachinaXX.Maker

Phase 1 Integration

Performance Enhancements

• Async Generation: Uses MakerEngine.RunAsync() for true asynchronous code generation
• Parallel Processing: Configurable parallel generation leveraging multiple CPU cores
• No Thread Blocking: Eliminated Task.Run() wrappers for proper async patterns
• Resource Efficiency: Better memory and CPU utilization through async I/O

Modern Error Handling

• Result Type Integration: Seamless conversion between Maker's Result<T> and MakerCLI's Results.Result
• Structured Errors: Rich error context with exception details preserved
• Functional Composition: Railway-oriented programming patterns for error handling
• Cancellation Support: Responsive to cancellation throughout the entire pipeline

Configuration Improvements

The build service automatically configures optimal settings for Phase 1 features:

var options = new MakerOptionsBuilder()
    .WithModelPath(modelPath)
    .WithModelFolderName(modelFolderName)
    .WithModelFileName(modelName)
    .WithTemplates(templatePath)
    .WithOutputPath("output")
    .EnableAsync(true)                              // Enable async processing
    .WithMaxParallelism(Environment.ProcessorCount) // Use available cores
    .Build();

Development

Building from Source

git clone https://github.com/your-org/MakerCLI.git
cd MakerCLI
dotnet restore
dotnet build

Running Tests

dotnet test

Project Structure

MakerCLI/
├── Program.cs                  # Host configuration and DI setup
├── Services/
│   ├── BuildService.cs         # Model building logic (Phase 1 async)
│   ├── PublishService.cs       # File deployment logic
│   └── BuildOrPublishService.cs # Main orchestration
├── Extensions/
│   └── ResultExtensions.cs     # Phase 1 Result type conversion utilities
├── Settings/
│   ├── Data.cs                 # Configuration data models
│   ├── Profile.cs              # AutoMapper profiles
│   ├── Reader.cs               # Configuration loading
│   └── SettingsDataExtensions.cs # Path resolution helpers
└── Results/
    └── Result.cs               # MakerCLI Result types

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Release Management

Current Version: 2.1.1

See CHANGELOG.md for detailed version history, release notes, and upgrade information.

Release Process

This project follows semantic versioning and maintains a comprehensive changelog. For information about:

• Version history and changes
• Upgrade procedures
• Breaking changes
• New features and bug fixes

Please refer to the CHANGELOG.md file.

Support

For questions and support, please open an issue on the GitHub repository.