feat: Maestro Plugin System

[dipcore]

Maestro Plugin System

Proposed changes

This PR introduces a comprehensive Plugin System for Maestro that enables developers to create custom commands as external plugins, significantly extending Maestro's automation capabilities beyond built-in commands.

Architecture Benefits

• Non-invasive: Plugins extend functionality without modifying core Maestro 🥇

• Type Safe: Plugin interface ensures consistent command behavior

• Isolated: Plugins run in isolated class loaders

• Extensible: New command types can be added without code changes

• Compatible: Existing flows continue to work unchanged

Key Features:

Plugin Architecture

• Created a new maestro-plugins module with a flexible plugin interface (CommandPlugin<T>)

• Implemented PluginRegistry for discovering, loading, and managing plugins

• Added support for both built-in and external JAR-based plugins using Java's ServiceLoader mechanism

• Plugins load from ~/.maestro/plugins directory by default, with --plugins-dir CLI option for custom locations

YAML Integration

• Seamless integration with existing Maestro YAML flows

• Plugin commands work alongside built-in commands with identical syntax

• Support for label and optional parameters in plugin commands

• Automatic parsing and validation of plugin command data

Execution Context

• Rich PluginExecutionContext providing access to:

  • Maestro driver for device interactions

  • JavaScript engine for script evaluation

  • Device capabilities and configuration

  • iOS XCTest runner integration

Example Plugins

• LogCommandPlugin: Enhanced logging with configurable levels

• WaitCommandPlugin: Extended wait functionality with custom parameters

• MultiTapCommandPlugin: Perform multiple taps with configurable delays and coordinates

• MultiSwipeCommandPlugin: Execute multiple swipes with direction/point-to-point support

• TypewriterCommandPlugin: Simulate realistic typing with character-by-character delays

Developer Experience

• Complete plugin template and documentation in examples/plugins/

• Gradle build system for easy plugin JAR creation

• Comprehensive error handling and validation

• Built-in testing framework for plugin development

Technical Implementation:

• Core Plugin Interface: Type-safe command parsing, validation, and execution

• Dynamic Loading: JAR-based plugin discovery with isolated class loaders

• CLI Integration: New --plugins-dir option and automatic plugin initialization

• Orchestra Integration: Plugin commands execute within the standard Maestro command pipeline

• Exception Handling: Dedicated plugin exception types for better debugging

Testing

• Unit Tests: Comprehensive test suite for PluginRegistry functionality

• Integration Tests: End-to-end plugin loading and execution validation

• Build System: Gradle tasks for plugin JAR creation and validation

• Manual Testing: Verified plugin loading from external JARs and built-in plugins

Video

Workflow which uses demo plugins:

[dipcore]

Guys it is ready for review. Please check it out.

[dipcore]

Here’s how I see benefits:

Maestro Cloud

Maestro Cloud runners can go with a set of plugins that deliver cloud-only features. These plugins, developed and maintained by the Maestro team, may be closed source and come pre-installed on cloud runners. They provide unique, thoroughly tested functionality, making Maestro Cloud an attractive choice for users seeking enhanced automation capabilities and reliability, without the need to write custom plugins or maintain community plugins.

Maintenance

Introducing the plugin system allows the Maestro team to focus on maintaining and improving the Maestro core and Maestro Cloud plugins. The core remains unchanged: existing core commands stay consistent, well-tested, and highly portable.

Community

With the plugin system, the community can now develop and share custom plugins, extending Maestro’s functionality to suit specific needs. While these custom plugins increase flexibility, their quality and maintenance are the responsibility of the community members who create them.

Guys, let me know what do you think about it.

[Angelk90]

@dipcore : Excellent work, would it be possible to publish the demo app code for future development?

[dipcore]

@herval @Leland-Takamine @Fishbowler Guys, this PR waits for your review.

[dipcore]

@dipcore : Excellent work, would it be possible to publish the demo app code for future development?

Thank you. The demo app is a simple expo application with a few screens and logs. There are no any functionality, it is simply to display demo plugins interactions. But, if you really need it I could share /src directory, so you can put it into bare expo app.

[Angelk90]

@dipcore : If you could share the repository, that would be great; we could use it for future testing.

If you don't want to share it, a repo with just the /src directory is fine.

[dipcore]

@Angelk90 Here is the demo app: https://github.com/dipcore/maestro-plugins-test-app

[dipcore]

Is this proposal rejected?