@mochabug/adaptkit/README.md

A cmd to create, emulate and publish Mochabug Adapt plugins

# @mochabug/adaptkit

**@mochabug/adaptkit** is the official CLI tool for developing and managing plugins for the Mochabug Adapt platform. Built with Node.js 22 compatibility, adaptkit streamlines the entire plugin development workflow.

## Key Features

- Create new plugin projects with scaffolding
- Add vertices (tasks) to existing plugins
- Emulate plugins locally for testing
- Publish plugins to the Mochabug Adapt platform
- Manage plugin versioning with semantic versioning

## Plugin Architecture

Plugins are composed of **vertices** - the fundamental building blocks that define tasks. Each vertex consists of:

### Executor (Required)
The core logic that performs tasks. Available types:
- **Action** - Performs tasks without external system interactions
- **Cron Trigger** - Executes tasks at scheduled intervals
- **External Trigger** - Responds to external endpoint events
- **Browser** - Runs tasks within a browser environment

### Configurator (Optional)
Provides UI for customizing executor behavior on the Mochabug Adapt platform.

## Installation

```bash
npm install -g @mochabug/adaptkit
```

## Commands

### Initialize a Plugin Project
```bash
adaptkit init
```
Creates a new plugin with `manifest.json`, executor/configurator templates, and schema files.

### Add Vertices to Your Plugin
```bash
adaptkit add
```
Interactively adds new vertices to your existing plugin project.

### Emulate Plugin Locally
```bash
adaptkit emulate
```
Test your plugin in a local environment. Requires the Mochabug Adapt sandbox:

```bash
docker run --rm -it -p 51001:51001 -p 51002:51002 -p 51003:51003 -p 51004:51004 -p 51005:51005 mochabug/adaptsandbox:latest
```

The 5 ports simulate different vertex types, the graphical interface, and the adaptkit publish endpoint.

### Publish to Mochabug Adapt
```bash
adaptkit publish
```
Deploy your plugin to the Mochabug Adapt platform for production use.

### Version Management
```bash
adaptkit version --patch  # Increment patch version
adaptkit version --minor  # Increment minor version
adaptkit version --major  # Increment major version
```
Updates the semantic version in your plugin's `manifest.json`.

## Node.js 22 Compatibility

Adaptkit is built with full Node.js 22 support, leveraging modern JavaScript features and native ES modules for optimal performance and compatibility.

## Documentation

For comprehensive documentation and API references, visit [Mochabug Developer Portal](https://developers.mochabug.com).

## Contributing

We welcome community contributions! Please [open an issue](https://github.com/mochabug/adaptkit/issues) or [submit a pull request](https://github.com/mochabug/adaptkit/pulls) on GitHub.

## License

Apache License 2.0