Documentation
¶
Overview ¶
Package plugin discovers repo-local Cobra commands written in Lua, Teal, or Fennel and merges them into an existing command tree.
A plugin is a directory containing a config.toml manifest and a run.{lua,tl,fnl} entrypoint:
.hex/command/hello/ ├── config.toml └── run.lua
config.toml:
use = "hello"
short = "Say hello"
[flags]
name = { type = "string", usage = "who to greet", value = "world" }
run.lua:
local name = cmd.flags().get_string("name")
print("Hello, " .. name .. "!")
Subdirectories become subcommands by listing their names in the parent manifest's `commands` array. Call Discover or LoadInto to turn a directory tree into *cobra.Command values; NewRuntimeExecutor wires the resulting commands to a real hex/lua Environment.
This package is the concrete instance of the escape hatch docs/adr/0007-lua-runtime-only.md reserved for later: hex/lua itself stays a bare runtime, and the plugin/discovery convention lives here instead.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadInto ¶
LoadInto discovers plugins under each of dirs (in order) and adds them to root as subcommands tagged with group. A command name already present on root — whether a built-in command or a plugin loaded from an earlier dir — wins; later duplicates are silently skipped. exec runs every discovered plugin's entrypoints; see NewRuntimeExecutor.
Types ¶
type Executor ¶
Executor runs a plugin entrypoint file (run.* or args.*) for one invocation of cmd with args. NewRuntimeExecutor builds the default implementation, which executes the file against a fresh hex/lua Environment.
func NewRuntimeExecutor ¶
func NewRuntimeExecutor(opts ...RuntimeOption) Executor
NewRuntimeExecutor returns an Executor that runs each plugin entrypoint against a fresh hex/lua Environment — one per invocation, so no state leaks between commands. The environment comes preloaded with the plugin runtime's module ("disk", "log") and globals (argv/argc, cmd, dump, explode, sleep); opts can preload additional modules.
type FlagConfig ¶
type FlagConfig struct {
Type string `toml:"type"`
Usage string `toml:"usage"`
Short string `toml:"short"`
Value any `toml:"value"`
}
FlagConfig describes one flag declared in a plugin's config.toml [flags] table. Type is "string"/"str", "bool"/"boolean", or "number", optionally suffixed "[]" for the slice variant.
type Group ¶
Group names the cobra.Group discovered commands are tagged with, so they show under their own heading in --help.
type Manifest ¶
type Manifest struct {
Use string `toml:"use"`
Aliases []string `toml:"aliases"`
Short string `toml:"short"`
Long string `toml:"long"`
Commands []string `toml:"commands"`
Flags map[string]FlagConfig `toml:"flags"`
}
Manifest is a plugin's config.toml.
type Plugin ¶
type Plugin struct {
Manifest
// contains filtered or unexported fields
}
Plugin is a loaded plugin directory: its manifest plus the filesystem location it was read from.
func Discover ¶
Discover reads dir's immediate subdirectories and loads each one that contains a config.toml as a Plugin. Non-plugin subdirectories are skipped. A missing dir is not an error — it returns (nil, nil) so callers can treat "no plugin directory" as a no-op.
type RuntimeOption ¶
type RuntimeOption func(*hexlua.Environment)
RuntimeOption configures the per-invocation Environment before a plugin entrypoint executes. Consumer apps use this to add bindings hex already ships for other Lua consumers, e.g.:
plugin.WithModule("config", (&configlua.Bindings{Store: store}).Loader)
func WithModule ¶
func WithModule(name string, loader glua.LGFunction) RuntimeOption
WithModule preloads an additional require()-able module for every plugin invocation made by the resulting Executor.
Source Files