113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# Squeebot CLI
|
|
|
|
Squeebot is a plugin runtime coordinator which, in its original intention, is used to create a multi-platform chat bot.
|
|
The core and CLI provide tooling to install, update, execute and coordinate JavaScript plugins.
|
|
The plugins all get access to a communication channel - a scoped event emitter - the flow of which can be controlled using channels.
|
|
|
|
Typically, the plugin repositories providing plugins that connect to a message/event source start with `service-` and the repositories
|
|
that provide plugins which do something with the messages/events start with `plugins-`.
|
|
|
|
```
|
|
services channel handlers
|
|
+-----+ | +----------+
|
|
| IRC | --> | --> | commands | - handles "message" event
|
|
+-----+ | +----------+ and resolves it with the response
|
|
| /|\
|
|
| | the plugin below accesses plugin above's API
|
|
| | to register a command
|
|
| |
|
|
+---------+ | +-----------------+
|
|
| Discord | --> | | calendar events |
|
|
+---------+ | +-----------------+
|
|
```
|
|
|
|
This package provides the runtime and tooling for Squeebot 3.x.x!
|
|
This package provides two binaries via npm: `squeebot` and `squeebotd`.
|
|
|
|
## Running Squeebot
|
|
1. Create an environment: `$ squeebot new <name> [<path>]`
|
|
2. Execute the environment in interactive mode using `squeebotd`: `$ squeebotd -i <path>/<name>.json`
|
|
3. Install plugins (documented below)
|
|
|
|
`squeebotd` just takes the path to the generated json file and creates all other necessary files and directories by itself.
|
|
The primary configuration will be located in `<path>/configs/squeebot.json`.
|
|
|
|
## Installing plugins
|
|
In order to install plugins, you have to add a repository. Repositories are JSON files served over HTTP.
|
|
|
|
For example, installing core plugins (Interactive mode `-i` on `squeebotd`):
|
|
1. `repository install https://squeebot.lunasqu.ee/pkg/plugins-core/repository.json`
|
|
2. `plugin install control simplecommands`
|
|
3. `plugin list`
|
|
|
|
## Interactive mode commands
|
|
The following commands are available when starting in interactive mode:
|
|
* `repository help` - Repository management commands
|
|
* `plugin help` - Plugin management commands
|
|
* `channel help` - Channel management commands
|
|
* `quit` - Exit Squeebot
|
|
* `inspector` - Enter JavaScript REPL (basically the same as running `node` without arguments)
|
|
|
|
## Creating a repository
|
|
In order to create a repository, you need to do the following:
|
|
1. Create a new repository: `$ squeebot repository new <name> [<path>]`
|
|
2. Build your new repository: `$ squeebot repository build <path>`
|
|
3. Your built plugins, both archived and unarchived, are in `<path>/.out`.
|
|
|
|
Repositories are created with a TypeScript build environment by default. If you do not wish to use TypeScript (not recommended) for your plugins,
|
|
add the `-t` flag to `squeebot repository new` command.
|
|
|
|
The build command supports a `-w` argument which will execute the entire build command again when you make changes (watch mode).
|
|
**Including deployments, if `-d` is present!**
|
|
|
|
### Creating plugins
|
|
Within your new repository, each directory you make will be a plugin. The plugin **must** contain the following:
|
|
1. `plugin.json` - Manifest for your plugin.
|
|
2. `plugin.js` - Has to be a JavaScript file which exports a class inherited from `Plugin` at `@squeebot/core/lib/plugin`.
|
|
3. `schema.json` - (optionally) include a JSON schema for the plugin's configuration.
|
|
|
|
**Note:** `plugin.js` only has to exist in the distribution, so `.ts` is fine, but you **have** to use `$ squeebot repository build <path>`
|
|
to build them into JavaScript files.
|
|
|
|
Plugin manifest (`plugin.json`) example:
|
|
```
|
|
{
|
|
"name": "plugin-name", // The name of your plugin, must match the name of the directory
|
|
"version": "0.0.0", // The version of your plugin, must be semantic versioning!
|
|
"description": "", // Optional description for this plugin
|
|
"tags": [], // Optional list of tags describing this plugin
|
|
"dependencies": [], // List of plugins this plugin depends on
|
|
"npmDependencies": [], // List of npm modules this plugin depends on. Supports versions, example 'thing@1.0.0'
|
|
}
|
|
```
|
|
|
|
### Deploying the repository
|
|
You can configure deployment options using a file called `deployment.json` in your repository root.
|
|
|
|
In order to activate your configured deployment, use the `-d` flag when building your repository. `-o` flag skips build and deploys immediately.
|
|
|
|
#### Development
|
|
```
|
|
{
|
|
"devSqueebot": "<full path to environment>.json",
|
|
}
|
|
```
|
|
|
|
Use `-d dev` to deploy this.
|
|
|
|
#### SSH deployment
|
|
```
|
|
{
|
|
"prod": {
|
|
"ssh": true,
|
|
"key": "<path to id_rsa>",
|
|
"host": "<ssh host>",
|
|
"user": "<ssh user>",
|
|
"target": "<full remote path>"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Official repositories
|
|
All official repositories [are here](https://git.icynet.eu/Squeebot). Production-ready builds are available to download via Squeebot CLI from `https://squeebot.lunasqu.ee/pkg/<repo name>/repository.json` by using the `repository install` command.
|