Skip to content
Kward Search API index

Class: Kward::PluginRegistry::DSL

Inherits:
Object
  • Object
show all
Defined in:
lib/kward/plugin_registry.rb

Overview

Public DSL object yielded by Kward.plugin blocks.

Plugin files normally interact with this object only through a block:

Examples:

Register a plugin command

Kward.plugin do |plugin|
  plugin.command "hello", description: "Say hello" do |args, ctx|
    name = args.strip.empty? ? "there" : args.strip
    ctx.say "Hello, #{name}."
  end
end

Instance Method Summary collapse

Constructor Details

#initialize(registry, path) ⇒ DSL

Creates an object for trusted plugin loading and dispatch.



173
174
175
176
 
# File 'lib/kward/plugin_registry.rb', line 173

def initialize(registry, path)
  @registry = registry
  @path = path
end

Instance Method Details

#command(name, description: "", argument_hint: "") {|args, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a slash command.

The command is available in the interactive CLI and through the RPC command bridge. Command names do not include the leading /.

Parameters:

  • name (String, #to_s) —

    command name without the leading slash

  • description (String) (defaults to: "") —

    short text shown in command listings

  • argument_hint (String) (defaults to: "") —

    optional usage hint for arguments

Yield Parameters:

  • args (String) —

    text after the command name

  • ctx (Context) —

    plugin execution context



190
191
192
 
# File 'lib/kward/plugin_registry.rb', line 190

def command(name, description: "", argument_hint: "", &block)
  @registry.register_command(name, description: description, argument_hint: argument_hint, path: @path, &block)
end

#footer {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers or replaces the custom footer renderer.

Only one footer renderer is active. If multiple plugins register one, the later renderer replaces the earlier renderer.

Yield Parameters:

  • ctx (Context) —

    plugin execution context



202
203
204
 
# File 'lib/kward/plugin_registry.rb', line 202

def footer(&block)
  @registry.register_footer(path: @path, &block)
end

#hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil) {|event, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a lifecycle hook handler.

Hooks are deterministic runtime callbacks around Kward lifecycle events. They can return a Hooks::Decision, a decision hash, a decision string, or nil to allow the operation.

Parameters:

  • event (String, #to_s) —

    lifecycle event name

  • id (String, nil) (defaults to: nil) —

    stable hook identifier for logs and diagnostics

  • description (String) (defaults to: "") —

    short human-readable purpose

  • order (Integer) (defaults to: 100) —

    lower values run first

  • match (Hash, nil) (defaults to: nil) —

    optional event selector

Yield Parameters:

  • event (Hooks::Event) —

    immutable lifecycle event

  • ctx (Context) —

    plugin execution context and decision helpers



234
235
236
 
# File 'lib/kward/plugin_registry.rb', line 234

def hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, &block)
  @registry.register_hook(event, id: id, description: description, order: order, match: match, failure_policy: failure_policy, path: @path, &block)
end

#interactive_command(name, rows:, fps: 30, description: "", argument_hint: "") {|ui, ctx| ... } ⇒ void

This method returns an undefined value.

Registers an interactive command that takes over the composer region with a Kward-driven render and input loop. The handler receives an interactive controller object with a canvas API for drawing colored cells and reading keys. Useful for games, dashboards, and viewers.

Parameters:

  • name (String, #to_s) —

    command name without the leading slash

  • rows (Integer) —

    fixed canvas height in terminal rows

  • fps (Numeric) (defaults to: 30) —

    frame rate for tick callbacks (1-120, default 30)

  • description (String) (defaults to: "") —

    short text shown in command listings

  • argument_hint (String) (defaults to: "") —

    optional usage hint for arguments

Yield Parameters:

  • ui (Object) —

    interactive controller with canvas and key API

  • ctx (Context) —

    plugin execution context



264
265
266
 
# File 'lib/kward/plugin_registry.rb', line 264

def interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", &block)
  @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
end

#on_transcript_event {|event, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a live transcript event observer.

Observer errors are caught and reported as warnings so a plugin cannot crash the active turn by raising from an event handler.

Yield Parameters:



215
216
217
 
# File 'lib/kward/plugin_registry.rb', line 215

def on_transcript_event(&block)
  @registry.register_transcript_event(path: @path, &block)
end

#prompt_context {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers prompt context text injected into future system prompts.

Keep this text short and never include secrets. The returned string can be sent to the active model as part of Kward's system instructions.

Yield Parameters:

  • ctx (Context) —

    plugin execution context



246
247
248
 
# File 'lib/kward/plugin_registry.rb', line 246

def prompt_context(&block)
  @registry.register_prompt_context(path: @path, &block)
end