Module: AIA::ConfigValidator

Defined in:
lib/aia/config/validator.rb

Class Method Summary collapse

Class Method Details

.configure_prompt_manager(config) ⇒ Object 



522
523
524
525
526
527
528
 
# File 'lib/aia/config/validator.rb', line 522

def configure_prompt_manager(config)
  # PM v1.0.0 uses ERB parameters (<%= param %>) instead of regex-based extraction.
  # parameter_regex is deprecated and ignored.
  if config.prompts.parameter_regex
    warn "Warning: --regex / parameter_regex is deprecated. PM v1.0.0 uses ERB parameters (<%= param %>)."
  end
end

.dump_config(config, file) ⇒ Object

Dump configuration to file

Parameters:

  • config (AIA::Config) —

    the configuration to dump

  • file (String) —

    the file path to dump to



558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
 
# File 'lib/aia/config/validator.rb', line 558

def dump_config(config, file)
  ext = File.extname(file).downcase

  config_hash = config.to_h

  # Remove runtime keys
  config_hash.delete(:prompt_id)
  config_hash.delete(:dump_file)

  content = case ext
            when '.yml', '.yaml'
              require 'yaml'
              YAML.dump(config_hash.transform_keys(&:to_s))
            else
              raise "Unsupported config file format: #{ext}. Use .yml or .yaml"
            end

  File.write(file, content)
  puts "Config successfully dumped to #{file}"
end

.filter_mcp_servers(config) ⇒ Object 



350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/aia/config/validator.rb', line 350

def filter_mcp_servers(config)
  servers  = config.mcp_servers || []
  use_list  = Array(config.mcp_use)
  skip_list = Array(config.mcp_skip)

  if !use_list.empty?
    servers.select { |s| use_list.include?(s[:name] || s['name']) }
  elsif !skip_list.empty?
    servers.reject { |s| skip_list.include?(s[:name] || s['name']) }
  else
    servers
  end
end

.first_sentences(text, count) ⇒ Object 



421
422
423
424
425
426
427
 
# File 'lib/aia/config/validator.rb', line 421

def first_sentences(text, count)
  # Normalize whitespace: collapse newlines and multiple spaces
  normalized = text.gsub(/\s*\n\s*/, ' ').gsub(/\s{2,}/, ' ').strip
  sentences  = normalized.scan(/[^.!?]*[.!?]/)
  result     = sentences.first(count).join.strip
  result.empty? ? normalized : result
end

.generate_completion_script(shell) ⇒ Object 



503
504
505
506
507
508
509
510
511
 
# File 'lib/aia/config/validator.rb', line 503

def generate_completion_script(shell)
  script_path = File.join(File.dirname(__FILE__), "../aia_completion.#{shell}")

  if File.exist?(script_path)
    puts File.read(script_path)
  else
    warn "ERROR: The shell '#{shell}' is not supported or the completion script is missing."
  end
end

.handle_completion_script(config) ⇒ Object 



496
497
498
499
500
501
 
# File 'lib/aia/config/validator.rb', line 496

def handle_completion_script(config)
  return unless config.completion

  generate_completion_script(config.completion)
  exit
end

.handle_dump_config(config) ⇒ Object 



187
188
189
190
191
192
 
# File 'lib/aia/config/validator.rb', line 187

def handle_dump_config(config)
  return unless config.dump_file

  dump_config(config, config.dump_file)
  exit 0
end

.handle_executable_prompt(config) ⇒ Object 



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/aia/config/validator.rb', line 92

def handle_executable_prompt(config)
  # Auto-detect: no prompt_id, first context_file starts with shebang
  return unless config.prompt_id.nil?
  return unless config.context_files && !config.context_files.empty?

  candidate = config.context_files.first
  return unless File.exist?(candidate) && File.readable?(candidate)

  first_line = File.open(candidate, &:readline).strip rescue nil
  return unless first_line&.start_with?('#!')

  # This is an executable prompt — the file content IS the prompt
  config.context_files.shift
  config.executable_prompt_content = File.read(candidate).lines[1..].join
  config.prompt_id = '__EXECUTABLE_PROMPT__'
end

.handle_fuzzy_search_prompt_id(config) ⇒ Object 



159
160
161
162
163
 
# File 'lib/aia/config/validator.rb', line 159

def handle_fuzzy_search_prompt_id(config)
  return unless (config.flags.fuzzy == true) && (config.prompt_id.nil? || config.prompt_id.empty?)

  config.prompt_id = '__FUZZY_SEARCH__'
end

.handle_list_skills(config) ⇒ Object 



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/aia/config/validator.rb', line 243

def handle_list_skills(config)
  return unless config.list_skills

  skills_dir = AIA.config.skills.dir

  unless Dir.exist?(skills_dir)
    $stderr.puts "No skills directory found at #{skills_dir}"
    exit 0
  end

  skill_dirs = Dir.glob("*/SKILL.md", base: skills_dir).map { |f| File.dirname(f) }.sort

  if skill_dirs.empty?
    $stderr.puts "No skills found in #{skills_dir}"
    exit 0
  end

  skill_dirs.each do |skill_name|
    skill_md = File.join(skills_dir, skill_name, 'SKILL.md')
    fm = AIA::SkillUtils.parse_front_matter(skill_md)

    puts "## #{skill_name}"
    puts
    puts "| Key | Value |"
    puts "|-----|-------|"
    fm.each do |key, value|
      puts "| #{key} | #{value} |"
    end
    puts
  end

  exit 0
end

.handle_list_tools(config) ⇒ Object 



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/aia/config/validator.rb', line 219

def handle_list_tools(config)
  return unless config.list_tools

  local_tools = load_local_tools(config)
  mcp_tool_groups = {}

  if config.mcp_list
    mcp_tool_groups = load_mcp_tools_grouped(config)
  end

  if local_tools.empty? && mcp_tool_groups.empty?
    $stderr.puts "No tools available."
    exit 0
  end

  if $stdout.tty?
    list_tools_terminal(local_tools, mcp_tool_groups)
  else
    list_tools_markdown(local_tools, mcp_tool_groups)
  end

  exit 0
end

.handle_mcp_list(config) ⇒ Object 



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/aia/config/validator.rb', line 194

def handle_mcp_list(config)
  return unless config.mcp_list
  return if config.list_tools  # defer to handle_list_tools for combined output

  servers = filter_mcp_servers(config)

  if servers.empty?
    puts "No MCP servers configured."
  else
    label = mcp_filter_active?(config) ? "Active" : "Configured"
    puts "#{label} MCP servers:\n\n"
    servers.each do |server|
      name    = server[:name]    || server['name']    || '(unnamed)'
      command = server[:command] || server['command']  || '(no command)'
      args    = server[:args]    || server['args']     || []
      args_str = args.empty? ? '' : " #{args.join(' ')}"
      puts "  #{name}"
      puts "    command: #{command}#{args_str}"
      puts
    end
  end

  exit 0
end

.handle_stdin_as_prompt(config) ⇒ Object 



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/aia/config/validator.rb', line 109

def handle_stdin_as_prompt(config)
  return unless config.prompt_id.nil?
  return unless config.stdin_content && !config.stdin_content.strip.empty?

  content = config.stdin_content

  # Strip shebang line if present (e.g., piped from an executable prompt)
  if content.lines.first&.strip&.start_with?('#!')
    content = content.lines[1..].join
  end

  config.executable_prompt_content = content
  config.stdin_content = nil  # prevent double-processing in build_prompt_text
  config.prompt_id = '__EXECUTABLE_PROMPT__'
end

.list_tools_markdown(local_tools, mcp_tool_groups) ⇒ Object 



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/aia/config/validator.rb', line 305

def list_tools_markdown(local_tools, mcp_tool_groups)
  total = local_tools.size + mcp_tool_groups.values.sum(&:size)
  sources = 1 + mcp_tool_groups.size

  puts "# Available Tools"
  puts
  puts "> #{total} tools from #{sources} source#{'s' if sources > 1}"
  puts

  unless local_tools.empty?
    puts "## Local Tools (#{local_tools.size})"
    puts
    local_tools.each { |tool| print_tool_markdown(tool) }
  end

  mcp_tool_groups.each do |server_name, tools|
    puts "## MCP: #{server_name} (#{tools.size})"
    puts
    tools.each { |tool| print_tool_markdown(tool) }
  end
end

.list_tools_terminal(local_tools, mcp_tool_groups) ⇒ Object 



277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/aia/config/validator.rb', line 277

def list_tools_terminal(local_tools, mcp_tool_groups)
  width  = (ENV['COLUMNS'] || 80).to_i - 4
  indent = '    '

  unless local_tools.empty?
    puts "Local Tools:\n\n"
    local_tools.each { |tool| print_tool_terminal(tool, width, indent) }
  end

  mcp_tool_groups.each do |server_name, tools|
    puts "MCP: #{server_name} (#{tools.size} tools)\n\n"
    tools.each { |tool| print_tool_terminal(tool, width, indent) }
  end
end

.load_local_tools(config) ⇒ Object 



381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/aia/config/validator.rb', line 381

def load_local_tools(config)
  # Load required libraries (with gem activation and lazy-load triggering)
  Array(config.require_libs).each do |lib|
    begin
      Adapter::GemActivator.activate_gem_for_require(lib)
      require lib
      Adapter::GemActivator.trigger_tool_loading(lib)
    rescue LoadError => e
      warn "Warning: Failed to require '#{lib}': #{e.message}"
      warn "Hint: Make sure the gem is installed: gem install #{lib}"
    rescue StandardError => e
      warn "Warning: Error in library '#{lib}': #{e.class} - #{e.message}"
    end
  end

  # Load tool files
  Array(config.tools&.paths).each do |path|
    expanded = File.expand_path(path)
    if File.exist?(expanded)
      require expanded
    else
      warn "Warning: Tool file not found: #{path}"
    end
  rescue LoadError, StandardError => e
    warn "Warning: Failed to load tool '#{path}': #{e.message}"
  end

  # Scan ObjectSpace for RubyLLM::Tool subclasses
  ObjectSpace.each_object(Class).select do |klass|
    next false unless klass < RubyLLM::Tool

    begin
      klass.new
      true
    rescue ArgumentError, LoadError, StandardError
      false
    end
  end
end

.load_mcp_tools_grouped(config) ⇒ Object 



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/aia/config/validator.rb', line 429

def load_mcp_tools_grouped(config)
  servers = filter_mcp_servers(config)
  return {} if servers.empty?

  # Suppress MCP logger noise during listing
  quiet_mcp_logger

  groups = {}
  default_timeout = 8_000

  servers.each do |server|
    name    = server[:name]    || server['name']
    command = server[:command] || server['command']
    args    = server[:args]    || server['args'] || []
    env     = server[:env]     || server['env']  || {}

    raw_timeout = server[:timeout] || server['timeout'] || default_timeout
    timeout = raw_timeout.to_i < 1000 ? (raw_timeout.to_i * 1000) : raw_timeout.to_i
    timeout = [timeout, 30_000].min

    mcp_config = { command: command, args: Array(args) }
    mcp_config[:env] = env unless env.empty?

    begin
      $stderr.print "MCP: Connecting to #{name}..."
      $stderr.flush

      client = begin
        RubyLLM::MCP.add_client(
          name: name, transport_type: :stdio,
          config: mcp_config, request_timeout: timeout, start: false
        )
      rescue ArgumentError
        RubyLLM::MCP.add_client(
          name: name, transport_type: :stdio,
          config: mcp_config, start: false
        )
      end

      client = RubyLLM::MCP.clients[name]
      client.start

      if client.alive?
        server_tools = client.tools rescue []
        groups[name] = server_tools
        $stderr.puts " #{server_tools.size} tools"
      else
        $stderr.puts " failed"
      end
    rescue StandardError => e
      $stderr.puts " error: #{e.message}"
    end
  end

  groups
end

.mcp_filter_active?(config) ⇒ Boolean

Returns:

  • (Boolean) 


364
365
366
 
# File 'lib/aia/config/validator.rb', line 364

def mcp_filter_active?(config)
  !Array(config.mcp_use).empty? || !Array(config.mcp_skip).empty?
end

.nest_markdown_headings(text, parent_level) ⇒ Object

Adjusts any markdown headings in text so they nest under the given parent heading level. e.g. with parent_level=3 (###), a “# Foo” becomes “#### Foo” and “## Bar” becomes “##### Bar”. Handles headings with optional leading whitespace.



343
344
345
346
347
348
 
# File 'lib/aia/config/validator.rb', line 343

def nest_markdown_headings(text, parent_level)
  text.gsub(/^[ \t]*(\#{1,6})\s/) do |match|
    existing = $1
    "#" * (existing.length + parent_level) + " "
  end
end

.normalize_boolean_flag(flags_section, flag) ⇒ Object 



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/aia/config/validator.rb', line 171

def normalize_boolean_flag(flags_section, flag)
  value = flags_section.send(flag)
  return if [TrueClass, FalseClass].include?(value.class)

  normalized = case value
               when nil, '', 'false', false
                 false
               when 'true', true
                 true
               else
                 true
               end

  flags_section.send("#{flag}=", normalized)
end

.normalize_boolean_flags(config) ⇒ Object 



165
166
167
168
169
 
# File 'lib/aia/config/validator.rb', line 165

def normalize_boolean_flags(config)
  normalize_boolean_flag(config.flags, :chat)
  normalize_boolean_flag(config.flags, :fuzzy)
  normalize_boolean_flag(config.flags, :consensus)
end

.prepare_pipeline(config) ⇒ Object 



530
531
532
533
534
 
# File 'lib/aia/config/validator.rb', line 530

def prepare_pipeline(config)
  return if config.prompt_id.nil? || config.prompt_id.empty? || config.prompt_id == config.pipeline.first

  config.pipeline.prepend(config.prompt_id)
end

.print_tool_markdown(tool) ⇒ Object 



327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/aia/config/validator.rb', line 327

def print_tool_markdown(tool)
  name = tool.respond_to?(:name) ? tool.name : tool.class.name
  desc = tool.respond_to?(:description) ? tool.description.to_s.strip : ''

  puts "### `#{name}`"
  puts
  unless desc.empty?
    puts nest_markdown_headings(desc, 3)
    puts
  end
end

.print_tool_terminal(tool, width, indent) ⇒ Object 



292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/aia/config/validator.rb', line 292

def print_tool_terminal(tool, width, indent)
  name = tool.respond_to?(:name) ? tool.name : tool.class.name
  desc = tool.respond_to?(:description) ? tool.description.to_s.strip : ''

  puts "  #{name}"
  unless desc.empty?
    brief = first_sentences(desc, 3)
    wrapped = WordWrapper::MinimumRaggedness.new(width, brief).wrap
    wrapped.split("\n").each { |line| puts "#{indent}#{line}" }
  end
  puts
end

.process_prompt_id_from_args(config, remaining_args) ⇒ Object 



68
69
70
71
72
73
74
75
76
77
 
# File 'lib/aia/config/validator.rb', line 68

def process_prompt_id_from_args(config, remaining_args)
  return if remaining_args.empty?

  maybe_id = remaining_args.first
  maybe_id_plus = File.join(config.prompts.dir, maybe_id + config.prompts.extname)

  if AIA.bad_file?(maybe_id) && AIA.good_file?(maybe_id_plus)
    config.prompt_id = remaining_args.shift
  end
end

.process_role_configuration(config) ⇒ Object 



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/aia/config/validator.rb', line 132

def process_role_configuration(config)
  role = config.prompts.role
  return if role.nil? || role.empty?

  roles_prefix = config.prompts.roles_prefix

  unless AIA::SkillUtils.path_based_id?(role) || roles_prefix.nil? || roles_prefix.empty? || role.start_with?(roles_prefix)
    config.prompts.role = "#{roles_prefix}/#{role}"
    role = config.prompts.role
  end

  config.prompts.roles_dir ||= File.join(config.prompts.dir, roles_prefix.to_s)

  # In chat-only mode (no prompt_id), leave the role configured so ChatLoop
  # can inject it as initial context. Promoting it to prompt_id would cause
  # PM to receive the role path as a literal string rather than file content.
  return if config.flags&.chat == true

  if config.prompt_id.nil? || config.prompt_id.empty?
    unless role.nil? || role.empty?
      config.prompt_id = role
      config.pipeline.prepend(config.prompt_id)
      config.prompts.role = ''
    end
  end
end

.process_stdin_content ⇒ Object 



53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/aia/config/validator.rb', line 53

def process_stdin_content
  stdin_content = String.new

  if !STDIN.tty? && !STDIN.closed?
    begin
      stdin_content << "\n" + STDIN.read
      STDIN.reopen('/dev/tty')
    rescue => _
      # If we can't reopen, continue without error
    end
  end

  stdin_content
end

.quiet_mcp_logger ⇒ Object 



486
487
488
489
490
491
492
493
494
 
# File 'lib/aia/config/validator.rb', line 486

def quiet_mcp_logger
  if defined?(RubyLLM::MCP) && RubyLLM::MCP.respond_to?(:config)
    mcp_config = RubyLLM::MCP.config
    if mcp_config.respond_to?(:logger=)
      quiet = Logger.new(File::NULL)
      mcp_config.logger = quiet
    end
  end
end

.require_tool_files(config) ⇒ Object 



368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/aia/config/validator.rb', line 368

def require_tool_files(config)
  Array(config.tools&.paths).each do |path|
    expanded = File.expand_path(path)
    if File.exist?(expanded)
      require expanded
    else
      warn "Warning: Tool file not found: #{path}"
    end
  rescue LoadError, StandardError => e
    warn "Warning: Failed to load tool '#{path}': #{e.message}"
  end
end

.tailor(config) ⇒ AIA::Config

Tailor and validate the configuration

Parameters:

  • config (AIA::Config) —

    the configuration to validate

Returns:



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/aia/config/validator.rb', line 19

def tailor(config)
  remaining_args = config.remaining_args&.dup || []
  config.remaining_args = nil

  # Process STDIN content if available
  stdin_content = process_stdin_content
  config.stdin_content = stdin_content if stdin_content && !stdin_content.strip.empty?

  # Require tool files early so AIA::Directive subclasses defined in them
  # are registered into PM.directives before PromptHandler.new is called.
  require_tool_files(config)

  # Process arguments and validate
  process_prompt_id_from_args(config, remaining_args)
  validate_and_set_context_files(config, remaining_args)
  handle_executable_prompt(config)
  handle_stdin_as_prompt(config)
  handle_dump_config(config)
  handle_mcp_list(config)
  handle_list_tools(config)
  handle_list_skills(config)
  handle_completion_script(config)
  validate_required_prompt_id(config)
  process_role_configuration(config)
  handle_fuzzy_search_prompt_id(config)
  normalize_boolean_flags(config)
  validate_final_prompt_requirements(config)
  configure_prompt_manager(config)
  prepare_pipeline(config)
  validate_pipeline_prompts(config)

  config
end

.validate_and_set_context_files(config, remaining_args) ⇒ Object 



79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/aia/config/validator.rb', line 79

def validate_and_set_context_files(config, remaining_args)
  return if remaining_args.empty?

  bad_files = remaining_args.reject { |filename| AIA.good_file?(filename) }
  if bad_files.any?
    warn "Error: The following files do not exist: #{bad_files.join(', ')}"
    exit 1
  end

  config.context_files ||= []
  config.context_files += remaining_args
end

.validate_final_prompt_requirements(config) ⇒ Object 



513
514
515
516
517
518
519
520
 
# File 'lib/aia/config/validator.rb', line 513

def validate_final_prompt_requirements(config)
  chat_mode = config.flags.chat == true
  fuzzy_mode = config.flags.fuzzy == true
  if !chat_mode && !fuzzy_mode && (config.prompt_id.nil? || config.prompt_id.empty?) && (config.context_files.nil? || config.context_files.empty?)
    warn "Error: A prompt ID is required unless using --chat, --fuzzy, or providing context files. Use -h or --help for help."
    exit 1
  end
end

.validate_pipeline_prompts(config) ⇒ Object 



536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
 
# File 'lib/aia/config/validator.rb', line 536

def validate_pipeline_prompts(config)
  return if config.pipeline.empty?

  and_exit = false

  config.pipeline.each do |prompt_id|
    next if prompt_id.nil? || prompt_id.empty? || prompt_id == '__FUZZY_SEARCH__' || prompt_id == '__EXECUTABLE_PROMPT__'

    prompt_file_path = File.join(config.prompts.dir, "#{prompt_id}#{config.prompts.extname}")
    unless File.exist?(prompt_file_path)
      warn "Error: Prompt ID '#{prompt_id}' does not exist at #{prompt_file_path}"
      and_exit = true
    end
  end

  exit(1) if and_exit
end

.validate_required_prompt_id(config) ⇒ Object 



125
126
127
128
129
130
 
# File 'lib/aia/config/validator.rb', line 125

def validate_required_prompt_id(config)
  return unless config.prompt_id.nil? && !(config.flags.chat == true) && !(config.flags.fuzzy == true)

  warn "Error: A prompt ID is required unless using --chat, --fuzzy, or providing context files. Use -h or --help for help."
  exit 1
end