revamp plugin system with entry points

[abc8747]

Previously, plugins are 1) not independently distributable, 2) uses ast/sys.path hacks to scan plugin metadata in a local directory and 3) lacks a way to properly manage background threads. Following #19 (comment) and #28, this PR implements and closes #24.

Following the approach in tangram, plugins are now normal Python packages exposing a Plugin value through the minisky.plugins entry-point group:

[project.entry-points."minisky.plugins"]
example = "minisky_example:plugin"

which points to a build function inside the plugin:

from minisky import plugin as plugin_api

# executed on "plugin startup"
def build(
    context: plugin_api.PluginContext[ExampleConfig],
) -> plugin_api.PluginSpec:
    # context here owns construction for one load attempt.
    component = context.mount(Example(context.config, context.python_random))
    return context.finish()


plugin = plugin_api.Plugin(
    build=build,
    config_class=ExampleConfig,
)

Mounted components declare their contributions:

class Example(plugin_api.Entity):
    @plugin_api.command(arguments="txt,[int]")
    def passengers(self, callsign: str, count: int = -1) -> tuple[bool, str]:
        ...

    @plugin_api.hook("update", interval=5.0)
    def update(self) -> None:
        ...

Replaceable implementations are also now explicitly contributed by the plugin:

@plugin_api.replacement
class CustomAutoPilot(Autopilot):
    ...

# then in the build function, register it so the SELECTIMPL command works...
return context.finish(replacements=(CustomAutoPilot,))

Plugins can also provide an FastAPI-style async lifespan to manage resources like httpx/postgres like:

@asynccontextmanager
async def lifespan(runtime: plugin_api.PluginRuntime):
    resource = await open_resource()
    try:
        yield
    finally:
        await resource.aclose()

The plugin_path and enabled_plugins settings are removed. The [plugins.<id>] now stores the plugin-specific configuration, much like tangram, and is validated before calling its build function.

Note that plugins are not loaded by default and must be done via LOAD PLUGIN or await runtime.plugins.load_configured().

Future work planned but not included in this PR:

• replacing the command arguments DSL with Annotated[...]
• typed migration of core stack commands
• explicit replaceable-slot declarations
• preserving the plugin config generic through entry-point metadata

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	minisky	37ab076	Aug 01 2026, 02:24 PM