npm package: @squeebot/cli
Description: Squeebot v3 runtime, environments and configuration
Author: Evert "Diamond" Prants
Latest version: 3.7.0

# 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.