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.



182
183
184
185
 
# File 'lib/kward/plugin_registry.rb', line 182

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



199
200
201
 
# File 'lib/kward/plugin_registry.rb', line 199

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



211
212
213
 
# File 'lib/kward/plugin_registry.rb', line 211

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



243
244
245
 
# File 'lib/kward/plugin_registry.rb', line 243

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



273
274
275
 
# File 'lib/kward/plugin_registry.rb', line 273

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:



224
225
226
 
# File 'lib/kward/plugin_registry.rb', line 224

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



255
256
257
 
# File 'lib/kward/plugin_registry.rb', line 255

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

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

This method returns an undefined value.

Registers a plugin-owned chat type. id is a durable identifier used in persisted tab layouts and transport chat handles 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

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

    expose this chat through trusted local RPC

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

    allow external transport adapters to target this chat

  • local (Boolean) (defaults to: true) —

    expose this chat as an interactive local tab

  • 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



293
294
295
 
# File 'lib/kward/plugin_registry.rb', line 293

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

#transport(name, id:, capabilities: nil, execution_profile: nil) {|host, config| ... } ⇒ void

This method returns an undefined value.

Registers an external messaging or event transport. The factory is called when the transport runtime starts.

Parameters:

  • name (String) —

    human-readable transport name

  • id (String) —

    stable transport identifier

  • capabilities (Hash, Transport::Capabilities) (defaults to: nil) —

    supported features

Yield Parameters:

  • host (Object) —

    transport host

  • config (Object) —

    transport configuration



307
308
309
 
# File 'lib/kward/plugin_registry.rb', line 307

def transport(name, id:, capabilities: nil, execution_profile: nil, &block)
  @registry.register_transport(name, id: id, capabilities: capabilities, execution_profile: execution_profile, path: @path, &block)
end