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.



177
178
179
180
 
# File 'lib/kward/plugin_registry.rb', line 177

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



194
195
196
 
# File 'lib/kward/plugin_registry.rb', line 194

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



206
207
208
 
# File 'lib/kward/plugin_registry.rb', line 206

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



238
239
240
 
# File 'lib/kward/plugin_registry.rb', line 238

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



268
269
270
 
# File 'lib/kward/plugin_registry.rb', line 268

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:



219
220
221
 
# File 'lib/kward/plugin_registry.rb', line 219

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



250
251
252
 
# File 'lib/kward/plugin_registry.rb', line 250

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

#tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false) {|host, descriptor| ... } ⇒ void

This method returns an undefined value.

Registers a plugin-owned tab type for the interactive CLI. id is a durable identifier used in persisted tab layouts and must not change. The factory receives a PluginTabHost and a descriptor hash.

Parameters:

  • name (String) —

    command name used by /tab open <name>

  • id (String) —

    stable persisted tab type identifier

  • title (String) (defaults to: nil) —

    default tab label

  • singleton (Symbol) (defaults to: nil) —

    :global for one shared plugin runtime

  • transcript_events (Boolean) (defaults to: false) —

    allow global transcript observers to receive this tab's events

Yield Parameters:

  • host (PluginTabHost) —

    supported host dependencies

  • descriptor (Hash) —

    persisted tab descriptor



285
286
287
 
# File 'lib/kward/plugin_registry.rb', line 285

def tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, &block)
  @registry.register_tab_type(name, id: id, title: title, singleton: singleton, rpc: rpc, transcript_events: transcript_events, path: @path, &block)
end