Lua plugins

Project setup

1. Install the author tool for your BlokeBot release.
2. Run the project command.
3. Edit plugin.toml.
4. Run the generator after each manifest change.
5. Implement the declared handlers.
6. Validate the package.
7. Test the package.

• The project includes generated Lua types.
• The project includes declared access to BlokeBot.
• The project includes local tests.
• The project includes the files for the curated repository.

blokebot-plugin init community.my-plugin ./my-plugin
cd ./my-plugin
blokebot-plugin generate .
blokebot-plugin validate .
blokebot-plugin test .

Project files

plugin.toml

Defines the package and its access to BlokeBot.

lua/

Contains the Lua modules that you write.

.blokebot/lua/5.4/v1/

Contains the generated LuaLS types and handler skeletons.

.luarc.json

Adds the generated SDK to your LuaLS workspace.

tests.toml

Defines optional scenarios for the deterministic local test runner.

Permissions and security

BlokeBot fully trusts each curated plugin. The worker protects BlokeBot from plugin crashes and resource failures. It is not a security sandbox.

Lua 5.4 is the managed entry point. A package can also declare reviewed files for supported targets.

• Declare every host module that your plugin uses.
• Use only the plugin and feature identities that BlokeBot supplies for the invocation.
• Do not put protected values in logs.
• Do not put protected values in responses.
• Do not put protected values in page documents.
• If BlokeBot cancels an invocation, stop that invocation.

Plugin lifecycle

• Installation validates the package.
• Installation prepares its worker.
• Installation runs its migrations.
• Installation activates the selected release.

Install

BlokeBot completes the installation phases in this order.

Update

For each manual update, BlokeBot downloads the current tag again before it applies the update.

Installation fault

A migration or activation failure faults the selected installation. After a durable migration starts, BlokeBot does not resume the old code.

Remove

Removal deletes the package and all state that belongs to the plugin. BlokeBot does not provide a retention mode or a separate purge mode.

API reference

This wiki describes the plugin workflow.

• The generated reference lists all contract types.
• The generated reference lists all fields.
• The generated reference lists all outcomes.
• The generated reference lists all host functions.

• Generated v1 API reference
• Trusted plugin contract