Testing and releases

Author commands

• The release process validates each target.
• It runs local tests.
• It tags the package.
• It adds the package to the curated repository.

init

Creates a complete starter project in a new destination. It does not overwrite existing files.

generate

Validates plugin.toml and replaces only generated SDK files that contain markers.

validate

Validates the manifest and package for all supported runtime targets.

test

Runs tests.toml scenarios through the plugin worker for the current runtime target.

blokebot-plugin generate .
blokebot-plugin validate .
blokebot-plugin test .

tests.toml

tests.toml defines local test scenarios. The validated plugin package does not include this file.

The harness gives deterministic results for host calls. It does not install the plugin. It does not contact Twitch or third-party services.

• Add one scenario for each published handler path.
• List the expected host calls in their execution order.
• Add a migrationFailed scenario for an update failure fixture.
• Add a workerExited scenario for an intentional crash fixture.

name = "community.my-plugin"

[[scenarios]]
name = "starter-command"
workerMode = "admitted"
invocationKind = "command"
module = "main"
operation = "handle_command"
expectation = "returned"
input = { route = "plugin-starter", arguments = [] }
expectedHostCalls = ["settings.feature", "responses.chat"]

Repository layout

BlokeBot reads marketplace entries from each plugin.toml in the curated repository. The repository has no separate catalog file.

Place the package at plugins/<plugin-id>/. The directory name must equal the ID in plugin.toml.

• Curated plugin repository
• Community link queue example

plugins/
  community.my-plugin/
    plugin.toml
    lua/
      main.lua
    .blokebot/
    .luarc.json
    tests.toml

Release identity

1. Set declaredVersion to the release semantic version.
2. Set tag to the Git tag for that release.
3. Check that the package repository resolves the tag.
4. Run generate from the final package tree.
5. Run validate from the final package tree.
6. Run test from the final package tree.
7. Submit the package through the curated repository review process.

• For each download, BlokeBot records the version.
• For each download, BlokeBot records the tag.
• For each download, BlokeBot records a unique identity.

Updates

An administrator starts each update. BlokeBot downloads the current tag before it replaces the plugin.

A moved tag with the same version still creates a new download and worker.

If a tag is missing or a package is invalid, BlokeBot records the error for the administrator.

If migration or activation fails, BlokeBot also records the error.

Release checklist

• Check that the package contains plugin.toml and every declared file.
• Check that the generated SDK matches the final manifest.
• Check that validate accepts every declared runtime target.
• Check that test passes every declared scenario on the current runtime target.
• Check that the tag resolves to the reviewed package tree.
• Check that the package contains no protected value or token.
• Check that the package contains no production endpoint.