Skip to content
Kward Search API index

Class: Kward::PluginRegistry

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

Overview

Loads trusted user plugin files and provides the plugin DSL.

Plugins live in the user plugin directory, run as local Ruby code, and can register slash commands, one footer renderer, prompt context, and live transcript-event observers for CLI and RPC frontends.

This registry is intentionally trust-based, not a sandbox. Keep plugin loading restricted to ConfigFiles.plugin_paths, keep workspace-local code out of the load path, and expose immutable transcript views so plugins can observe state without corrupting active conversations.

Defined Under Namespace

Classes: Command, Context, DSL, HookHandler, InteractiveCommand, TabType, Transcript, TranscriptEvent

Constant Summary collapse

COMMAND_NAME_PATTERN = 
/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(reserved_commands: []) ⇒ PluginRegistry

Creates an object for trusted plugin loading and dispatch.



302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/kward/plugin_registry.rb', line 302

def initialize(reserved_commands: [])
  @reserved_commands = reserved_commands.map(&:to_s)
  @commands = {}
  @interactive_commands = {}
  @tab_types = {}
  @tab_types_by_id = {}
  @footer = nil
  @footer_path = nil
  @transcript_event_handlers = []
  @prompt_context_renderers = []
  @hook_handlers = []
  @paths = []
end

Class Attribute Details

.loading_path ⇒ Object

Returns the value of attribute loading_path.



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

def loading_path
  @loading_path
end

.loading_registry ⇒ Object

Returns the value of attribute loading_registry.



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

def loading_registry
  @loading_registry
end

Instance Attribute Details

Returns plugin file currently responsible for footer output.

Returns:

  • (String, nil) —

    plugin file currently responsible for footer output



317
318
319
 
# File 'lib/kward/plugin_registry.rb', line 317

def footer_path
  @footer_path
end

#paths ⇒ Array<String> (readonly)

Returns plugin files successfully loaded by this registry.

Returns:

  • (Array<String>) —

    plugin files successfully loaded by this registry



320
321
322
 
# File 'lib/kward/plugin_registry.rb', line 320

def paths
  @paths
end

Class Method Details

.load(paths: ConfigFiles.plugin_paths, reserved_commands: []) ⇒ Object 



294
295
296
297
298
 
# File 'lib/kward/plugin_registry.rb', line 294

def load(paths: ConfigFiles.plugin_paths, reserved_commands: [])
  registry = new(reserved_commands: reserved_commands)
  paths.each { |path| registry.load_file(path) }
  registry
end

Instance Method Details

#command_for(name) ⇒ Object 



326
327
328
 
# File 'lib/kward/plugin_registry.rb', line 326

def command_for(name)
  @commands[name.to_s]
end

#commands ⇒ Object 



322
323
324
 
# File 'lib/kward/plugin_registry.rb', line 322

def commands
  @commands.values
end

#evaluate(path: nil, &block) ⇒ Object 



413
414
415
416
417
 
# File 'lib/kward/plugin_registry.rb', line 413

def evaluate(path: nil, &block)
  dsl = DSL.new(self, path)
  block.arity == 1 ? block.call(dsl) : dsl.instance_eval(&block)
  self
end

#footer_renderer ⇒ Object 



350
351
352
 
# File 'lib/kward/plugin_registry.rb', line 350

def footer_renderer
  @footer
end

#hook_handlers ⇒ Object 



362
363
364
 
# File 'lib/kward/plugin_registry.rb', line 362

def hook_handlers
  @hook_handlers.dup
end

#hook_manager ⇒ Object 



366
367
368
369
370
371
372
373
374
 
# File 'lib/kward/plugin_registry.rb', line 366

def hook_manager
  manager = Hooks::Manager.new
  @hook_handlers.each do |hook|
    manager.register(hook.event, id: hook.id, source: hook.path, order: hook.order, match: hook.match, failure_policy: hook.failure_policy) do |event, context|
      hook.handler.call(event, context)
    end
  end
  manager
end

#interactive_command_for(name) ⇒ Object 



334
335
336
 
# File 'lib/kward/plugin_registry.rb', line 334

def interactive_command_for(name)
  @interactive_commands[name.to_s]
end

#interactive_commands ⇒ Object 



330
331
332
 
# File 'lib/kward/plugin_registry.rb', line 330

def interactive_commands
  @interactive_commands.values
end

#load_file(path) ⇒ Object 



399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/kward/plugin_registry.rb', line 399

def load_file(path)
  previous_registry = self.class.loading_registry
  previous_path = self.class.loading_path
  self.class.loading_registry = self
  self.class.loading_path = path
  Kernel.load(path)
  @paths << path
rescue StandardError => e
  warn "Warning: skipping Kward plugin #{path}: #{e.message}"
ensure
  self.class.loading_registry = previous_registry
  self.class.loading_path = previous_path
end

#notify_transcript_event(event, context) ⇒ Object 



387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/kward/plugin_registry.rb', line 387

def notify_transcript_event(event, context)
  transcript_event = transcript_event_for(event)
  return unless transcript_event

  @transcript_event_handlers.each do |entry|
    entry[:handler].call(transcript_event, context)
  rescue StandardError => e
    warn "Warning: Kward plugin transcript event error in #{entry[:path]}: #{e.message}"
  end
  nil
end

#prompt_context(context) ⇒ Object 



376
377
378
379
380
381
382
383
384
385
 
# File 'lib/kward/plugin_registry.rb', line 376

def prompt_context(context)
  parts = []
  @prompt_context_renderers.each do |entry|
    rendered = entry[:renderer].call(context)
    parts << rendered.to_s unless rendered.to_s.empty?
  rescue StandardError => e
    warn "Warning: Kward plugin prompt context error in #{entry[:path]}: #{e.message}"
  end
  parts.empty? ? nil : parts.join("\n\n")
end

#prompt_context_renderers ⇒ Object 



358
359
360
 
# File 'lib/kward/plugin_registry.rb', line 358

def prompt_context_renderers
  @prompt_context_renderers.map { |entry| entry[:renderer] }
end

#register_command(name, description: "", argument_hint: "", path: nil, &handler) ⇒ Object 



419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/kward/plugin_registry.rb', line 419

def register_command(name, description: "", argument_hint: "", path: nil, &handler)
  name = name.to_s
  raise "Plugin command name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
  raise "Plugin command /#{name} requires a handler" unless handler

  if @reserved_commands.include?(name)
    warn "Warning: skipping Kward plugin command /#{name}: reserved command"
    return nil
  end
  if @commands.key?(name)
    warn "Warning: skipping duplicate Kward plugin command /#{name}: #{path}"
    return nil
  end

  @commands[name] = Command.new(
    name: name,
    description: description.to_s,
    argument_hint: argument_hint.to_s,
    path: path,
    handler: handler
  )
end

#register_footer(path: nil, &renderer) ⇒ Object 



484
485
486
487
488
489
490
 
# File 'lib/kward/plugin_registry.rb', line 484

def register_footer(path: nil, &renderer)
  raise "Plugin footer requires a renderer" unless renderer

  warn "Warning: replacing Kward plugin footer from #{@footer_path}: #{path}" if @footer
  @footer = renderer
  @footer_path = path
end

#register_hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, path: nil, &handler) ⇒ Object 



504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/kward/plugin_registry.rb', line 504

def register_hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, path: nil, &handler)
  event = event.to_s
  raise "Plugin hook event is required" if event.empty?
  raise "Plugin hook #{event} requires a handler" unless handler

  @hook_handlers << HookHandler.new(
    event: event,
    id: id&.to_s || "#{File.basename(path.to_s.empty? ? "plugin" : path)}:#{event}:#{@hook_handlers.length + 1}",
    description: description.to_s,
    path: path,
    order: order.to_i,
    match: match,
    failure_policy: failure_policy,
    handler: handler
  )
end

#register_interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", path: nil, &handler) ⇒ Object 



442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/kward/plugin_registry.rb', line 442

def register_interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", path: nil, &handler)
  name = name.to_s
  raise "Interactive command name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
  raise "Interactive command /#{name} requires a handler" unless handler

  if @reserved_commands.include?(name) || @commands.key?(name)
    warn "Warning: skipping Kward interactive command /#{name}: reserved command"
    return nil
  end
  if @interactive_commands.key?(name)
    warn "Warning: skipping duplicate Kward interactive command /#{name}: #{path}"
    return nil
  end

  @interactive_commands[name] = InteractiveCommand.new(
    name: name,
    description: description.to_s,
    argument_hint: argument_hint.to_s,
    rows: [[rows.to_i, 1].max, 1].max,
    fps: [[fps.to_f, 1].max, 120].min,
    path: path,
    handler: handler
  )
end

#register_prompt_context(path: nil, &renderer) ⇒ Object 



498
499
500
501
502
 
# File 'lib/kward/plugin_registry.rb', line 498

def register_prompt_context(path: nil, &renderer)
  raise "Plugin prompt context requires a renderer" unless renderer

  @prompt_context_renderers << { path: path, renderer: renderer }
end

#register_tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, path: nil, &handler) ⇒ Object 



467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
 
# File 'lib/kward/plugin_registry.rb', line 467

def register_tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, path: nil, &handler)
  name = name.to_s
  id = id.to_s
  raise "Plugin tab type name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
  raise "Plugin tab type id is required" if id.empty?
  raise "Plugin tab type #{name} requires a handler" unless handler

  if @tab_types.key?(name) || @tab_types_by_id.key?(id)
    warn "Warning: skipping duplicate Kward plugin tab type #{id}: #{path}"
    return nil
  end

  tab_type = TabType.new(id: id, name: name, title: title.to_s.empty? ? name.capitalize : title.to_s, singleton: singleton&.to_sym, rpc: rpc == true, transcript_events: transcript_events == true, path: path, handler: handler)
  @tab_types[name] = tab_type
  @tab_types_by_id[id] = tab_type
end

#register_transcript_event(path: nil, &handler) ⇒ Object 



492
493
494
495
496
 
# File 'lib/kward/plugin_registry.rb', line 492

def register_transcript_event(path: nil, &handler)
  raise "Plugin transcript event requires a handler" unless handler

  @transcript_event_handlers << { path: path, handler: handler }
end

#tab_type_for(name) ⇒ Object 



342
343
344
 
# File 'lib/kward/plugin_registry.rb', line 342

def tab_type_for(name)
  @tab_types[name.to_s]
end

#tab_type_for_id(id) ⇒ Object 



346
347
348
 
# File 'lib/kward/plugin_registry.rb', line 346

def tab_type_for_id(id)
  @tab_types_by_id[id.to_s]
end

#tab_types ⇒ Object 



338
339
340
 
# File 'lib/kward/plugin_registry.rb', line 338

def tab_types
  @tab_types.values
end

#transcript_event_handlers ⇒ Object 



354
355
356
 
# File 'lib/kward/plugin_registry.rb', line 354

def transcript_event_handlers
  @transcript_event_handlers.map { |entry| entry[:handler] }
end