igniter 0.5.0 → 0.5.1

data/examples/llm_tools.rb

@@ -6,18 +6,18 @@
 #   - Declarative metadata (description, param schema, required capabilities)
 #   - JSON schema generation for Anthropic / OpenAI APIs
 #   - Capability-based access guards (enforced before tool.call)
-#   - Automatic tool-use loop inside LLM::Executor#complete
-#   - ToolRegistry for global discovery and schema export
+#   - Automatic tool-use loop inside AI::Executor#complete
+#   - AI::ToolRegistry for global discovery and schema export
 #   - Tool reuse as regular Igniter::Contract compute nodes
 #
 # Requires: ANTHROPIC_API_KEY (skips live calls if absent)
 #
 # Run: bundle exec ruby examples/llm_tools.rb
 
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "igniter"
-require "igniter/tool"
-require "igniter/tool_registry"
-require "igniter/integrations/llm"
+require "igniter/core/tool"
+require "igniter/ai"
 
 puts "=" * 62
 puts "  Igniter::Tool Demo"
@@ -86,18 +86,18 @@ require "json"
 puts JSON.pretty_generate(Calculator.to_schema(:anthropic)).split("\n").map { |l| "    #{l}" }.join("\n")
 
 # ─────────────────────────────────────────────────────────────────────────────
-# [3] ToolRegistry
+# [3] AI::ToolRegistry
 # ─────────────────────────────────────────────────────────────────────────────
-puts "\n[3] ToolRegistry"
+puts "\n[3] AI::ToolRegistry"
 
-Igniter::ToolRegistry.register(Calculator, TimeNow, DatabaseLookup)
-puts "  Registered #{Igniter::ToolRegistry.size} tools: #{Igniter::ToolRegistry.all.map(&:tool_name).join(", ")}"
+Igniter::AI::ToolRegistry.register(Calculator, TimeNow, DatabaseLookup)
+puts "  Registered #{Igniter::AI::ToolRegistry.size} tools: #{Igniter::AI::ToolRegistry.all.map(&:tool_name).join(", ")}"
 
 # Capability filtering
-public_tools = Igniter::ToolRegistry.tools_for(capabilities: [])
+public_tools = Igniter::AI::ToolRegistry.tools_for(capabilities: [])
 puts "  Tools with no caps required: #{public_tools.map(&:tool_name).join(", ")}"
 
-db_tools = Igniter::ToolRegistry.tools_for(capabilities: %i[database_read])
+db_tools = Igniter::AI::ToolRegistry.tools_for(capabilities: %i[database_read])
 puts "  Tools available with :database_read: #{db_tools.map(&:tool_name).join(", ")}"
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -152,16 +152,16 @@ puts "  SKU-003: #{checker.result.product[:name]}"
 puts "  Stock:   #{checker.result.product[:stock]}  →  discount: #{(checker.result.discount[:rate] * 100).to_i}% (#{checker.result.discount[:reason]})"
 
 # ─────────────────────────────────────────────────────────────────────────────
-# [6] LLM::Executor with automatic tool-use loop
+# [6] AI::Executor with automatic tool-use loop
 #     (live call requires ANTHROPIC_API_KEY)
 # ─────────────────────────────────────────────────────────────────────────────
-puts "\n[6] LLM::Executor with automatic tool-use loop"
+puts "\n[6] AI::Executor with automatic tool-use loop"
 
 if ENV["ANTHROPIC_API_KEY"].to_s.empty?
   puts "  ANTHROPIC_API_KEY not set — skipping live call"
   puts "  (showing executor definition only)"
 
-  class ProductAgent < Igniter::LLM::Executor
+  class ProductAgent < Igniter::AI::Executor
     provider :anthropic
     model "claude-haiku-4-5-20251001"
     system_prompt "You are a helpful product assistant. Use tools to answer questions."
@@ -189,7 +189,7 @@ if ENV["ANTHROPIC_API_KEY"].to_s.empty?
   puts "    capabilities: #{ProductAgent.declared_capabilities.inspect}"
   puts "    max_iters:    #{ProductAgent.max_tool_iterations}"
 else
-  class ProductAgent < Igniter::LLM::Executor
+  class ProductAgent < Igniter::AI::Executor
     provider :anthropic
     model "claude-haiku-4-5-20251001"
     system_prompt "You are a helpful product assistant. Use tools to answer questions."
@@ -207,7 +207,7 @@ else
   begin
     answer = ProductAgent.new.call(question: "What is the price of SKU-001 and what is 15% of that price?")
     puts "  Agent: #{answer}"
-  rescue Igniter::LLM::Error => e
+  rescue Igniter::AI::Error => e
     puts "  LLM error: #{e.message}"
   end
 end
@@ -217,7 +217,7 @@ end
 # ─────────────────────────────────────────────────────────────────────────────
 puts "\n[7] Agent with restricted capabilities"
 
-class RestrictedAgent < Igniter::LLM::Executor
+class RestrictedAgent < Igniter::AI::Executor
   provider :anthropic
   model "claude-haiku-4-5-20251001"
   system_prompt "You are a limited assistant."
@@ -232,6 +232,6 @@ class RestrictedAgent < Igniter::LLM::Executor
 end
 
 puts "  RestrictedAgent.declared_capabilities: #{RestrictedAgent.declared_capabilities.inspect}"
-puts "  Tools it may safely call: #{Igniter::ToolRegistry.tools_for(capabilities: RestrictedAgent.declared_capabilities).map(&:tool_name).join(", ")}"
+puts "  Tools it may safely call: #{Igniter::AI::ToolRegistry.tools_for(capabilities: RestrictedAgent.declared_capabilities).map(&:tool_name).join(", ")}"
 
 puts "\nDone."

data/examples/mesh.rb

@@ -13,17 +13,19 @@
 #   pinned_to: "name"  — must call this exact peer; if it is down the node
 #                        fails with IncidentError signalling admin intervention.
 #
-# In production you would require "igniter/extensions/mesh" and configure real
+# In production you would require "igniter/cluster" and configure real
 # peer URLs.  Here we stub the HTTP layer so the example runs without any
 # actual servers.
 # ─────────────────────────────────────────────────────────────────────────────
 
-require "igniter/extensions/mesh"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/cluster"
 require "json"
 
 # ── 1. Configure the mesh ────────────────────────────────────────────────────
 
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.configure do |c|
   c.peer_name          = "api-node"
   c.local_capabilities = [:api]
 
@@ -37,8 +39,8 @@ Igniter::Mesh.configure do |c|
              capabilities: %i[audit]
 end
 
-puts "Mesh configured with #{Igniter::Mesh.config.peers.size} peers:"
-Igniter::Mesh.config.peers.each do |p|
+puts "Mesh configured with #{Igniter::Cluster::Mesh.config.peers.size} peers:"
+Igniter::Cluster::Mesh.config.peers.each do |p|
   puts "  #{p.name} (#{p.url}) — capabilities: #{p.capabilities.join(", ")}"
 end
 puts
@@ -115,8 +117,8 @@ end
 
 puts "=== Scenario A: capability routing — orders-node alive ==="
 
-Igniter::Mesh.reset!
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.reset!
+Igniter::Cluster::Mesh.configure do |c|
   c.add_peer "orders-node",
              url: "http://orders.internal:4567",
              capabilities: [:orders]
@@ -142,15 +144,15 @@ rescue Igniter::Error => e
   puts "  Error: #{e.message}"
 ensure
   Igniter::Server::Client.define_singleton_method(:new, &original_new)
-  Igniter::Mesh.reset!
+  Igniter::Cluster::Mesh.reset!
 end
 
 puts
 
 puts "=== Scenario B: capability routing — no alive peers (deferred) ==="
 
-Igniter::Mesh.reset!
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.reset!
+Igniter::Cluster::Mesh.configure do |c|
   c.add_peer "orders-node",
              url: "http://orders.internal:4567",
              capabilities: [:orders]
@@ -176,13 +178,13 @@ order_state = contract.execution.cache.fetch(:order_result)
 puts "  order_result status: #{order_state&.status.inspect}   (expected :pending)"
 
 Igniter::Server::Client.define_singleton_method(:new, &original_new)
-Igniter::Mesh.reset!
+Igniter::Cluster::Mesh.reset!
 puts
 
 puts "=== Scenario C: pinned_to routing — audit-node down (incident) ==="
 
-Igniter::Mesh.reset!
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.reset!
+Igniter::Cluster::Mesh.configure do |c|
   c.add_peer "audit-node",
              url: "http://audit.internal:4567",
              capabilities: [:audit]
@@ -205,7 +207,7 @@ puts "  error class:      #{audit_state&.error&.class}"
 puts "  error message:    #{audit_state&.error&.message}"
 
 Igniter::Server::Client.define_singleton_method(:new, &original_new)
-Igniter::Mesh.reset!
+Igniter::Cluster::Mesh.reset!
 puts
 
 # ── 6. GET /v1/manifest demo ─────────────────────────────────────────────────

data/examples/mesh_discovery.rb

@@ -7,7 +7,9 @@
 #
 # This example uses in-process stubs so no real HTTP servers are needed.
 
-require_relative "../lib/igniter/extensions/mesh"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/cluster"
 
 # ─── Shared contract ──────────────────────────────────────────────────────────
 class ProcessOrder < Igniter::Contract
@@ -21,7 +23,7 @@ class ProcessOrder < Igniter::Contract
 end
 
 # ─── Stub HTTP layer ──────────────────────────────────────────────────────────
-# In production each peer is a separate igniter-server process. Here we stub
+# In production each peer is a separate igniter-stack process. Here we stub
 # the HTTP client so the example runs inline.
 
 module ClientStubs
@@ -85,8 +87,22 @@ module ClientStubs
         end
       end
 
-      def register_peer(name:, url:, capabilities: [])
-        puts "  [seed] registered peer: #{name} @ #{url} caps=#{capabilities}"
+      def register_peer(name: nil, url: nil, capabilities: [], tags: [], metadata: {}, manifest: nil)
+        if manifest
+          peer_name = manifest.respond_to?(:peer_name) ? manifest.peer_name : manifest[:peer_name] || manifest["peer_name"]
+          peer_url = manifest.respond_to?(:url) ? manifest.url : manifest[:url] || manifest["url"]
+          peer_caps = manifest.respond_to?(:capabilities) ? manifest.capabilities : manifest[:capabilities] || manifest["capabilities"]
+          peer_tags = manifest.respond_to?(:tags) ? manifest.tags : manifest[:tags] || manifest["tags"]
+          peer_metadata = manifest.respond_to?(:metadata) ? manifest.metadata : manifest[:metadata] || manifest["metadata"]
+        else
+          peer_name = name
+          peer_url = url
+          peer_caps = capabilities
+          peer_tags = tags
+          peer_metadata = metadata
+        end
+
+        puts "  [seed] registered peer: #{peer_name} @ #{peer_url} caps=#{peer_caps} tags=#{peer_tags} metadata=#{peer_metadata}"
         { "registered" => true }
       end
     end
@@ -123,7 +139,10 @@ puts "=" * 60
 puts "Scenario 1: Dynamic discovery from seed"
 puts "=" * 60
 
-Igniter::Mesh.configure do |c|
+previous_remote_adapter = Igniter::Runtime.remote_adapter
+Igniter::Cluster.activate_remote_adapter!
+
+Igniter::Cluster::Mesh.configure do |c|
   c.peer_name          = "api-node"
   c.local_url          = "http://api-node:4567"
   c.local_capabilities = %i[api]
@@ -132,13 +151,13 @@ Igniter::Mesh.configure do |c|
 end
 
 puts "\nBefore start_discovery!:"
-puts "  Dynamic peers: #{Igniter::Mesh.config.peer_registry.size}"
+puts "  Dynamic peers: #{Igniter::Cluster::Mesh.config.peer_registry.size}"
 
-Igniter::Mesh.start_discovery!
+Igniter::Cluster::Mesh.start_discovery!
 
 puts "\nAfter start_discovery!:"
-puts "  Dynamic peers: #{Igniter::Mesh.config.peer_registry.size}"
-Igniter::Mesh.config.peer_registry.all.each do |p|
+puts "  Dynamic peers: #{Igniter::Cluster::Mesh.config.peer_registry.size}"
+Igniter::Cluster::Mesh.config.peer_registry.all.each do |p|
   puts "  - #{p.name} @ #{p.url} caps=#{p.capabilities}"
 end
 puts
@@ -183,15 +202,15 @@ puts "=" * 60
 
 # Simulate a new billing-node announcing itself via POST /v1/mesh/peers
 # In production this is done by the new peer calling start_discovery!
-new_peer = Igniter::Mesh::Peer.new(
+new_peer = Igniter::Cluster::Mesh::Peer.new(
   name:         "billing-node",
   url:          "http://billing-node:4567",
   capabilities: %i[billing]
 )
-Igniter::Mesh.config.peer_registry.register(new_peer)
+Igniter::Cluster::Mesh.config.peer_registry.register(new_peer)
 
 puts "  Registered billing-node into local registry"
-puts "  Peers with :billing capability: #{Igniter::Mesh.config.peer_registry.peers_with_capability(:billing).map(&:name)}"
+puts "  Peers with :billing capability: #{Igniter::Cluster::Mesh.config.peer_registry.peers_with_capability(:billing).map(&:name)}"
 puts
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -234,10 +253,11 @@ puts "=" * 60
 puts "Scenario 5: Static add_peer + dynamic discovery merged"
 puts "=" * 60
 
-Igniter::Mesh.stop_discovery!
-Igniter::Mesh.reset!
+Igniter::Cluster::Mesh.stop_discovery!
+Igniter::Cluster::Mesh.reset!
+Igniter::Runtime.remote_adapter = previous_remote_adapter
 
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.configure do |c|
   c.peer_name = "api-node"
   c.local_url = "http://api-node:4567"
   c.seeds     = %w[http://seed:4567]
@@ -246,22 +266,22 @@ Igniter::Mesh.configure do |c|
   c.add_peer "legacy-node", url: "http://legacy:4567", capabilities: %i[billing]
 end
 
-Igniter::Mesh.start_discovery!
+Igniter::Cluster::Mesh.start_discovery!
 
-static_names  = Igniter::Mesh.config.peers.map(&:name)
-dynamic_names = Igniter::Mesh.config.peer_registry.all.map(&:name)
+static_names  = Igniter::Cluster::Mesh.config.peers.map(&:name)
+dynamic_names = Igniter::Cluster::Mesh.config.peer_registry.all.map(&:name)
 
 puts "  Static peers:  #{static_names}"
 puts "  Dynamic peers: #{dynamic_names}"
 puts "  Combined (via router):"
-all_orders = Igniter::Mesh.router.instance_eval { all_capable_peers(:orders) }.map(&:name)
+all_orders = Igniter::Cluster::Mesh.router.instance_eval { all_capable_peers(:orders) }.map(&:name)
 puts "    :orders capable peers: #{all_orders}"
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Cleanup
 # ─────────────────────────────────────────────────────────────────────────────
-Igniter::Mesh.stop_discovery!
-Igniter::Mesh.reset!
+Igniter::Cluster::Mesh.stop_discovery!
+Igniter::Cluster::Mesh.reset!
 ClientStubs.uninstall!
 
 puts "\nDone."

data/examples/mesh_gossip.rb

@@ -8,7 +8,9 @@
 #
 # This example uses in-process stubs so no real HTTP servers are needed.
 
-require_relative "../lib/igniter/extensions/mesh"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/cluster"
 
 # ─── Shared contract ──────────────────────────────────────────────────────────
 class CheckInventory < Igniter::Contract
@@ -79,7 +81,7 @@ puts "=" * 60
 puts "Scenario 1: C's registry before gossip"
 puts "=" * 60
 
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.configure do |c|
   c.peer_name          = NODE_C[:name]
   c.local_url          = NODE_C[:url]
   c.local_capabilities = NODE_C[:capabilities].map(&:to_sym)
@@ -89,16 +91,16 @@ Igniter::Mesh.configure do |c|
 end
 
 # C initially knows A (as if bootstrapped from a seed earlier)
-Igniter::Mesh.config.peer_registry.register(
-  Igniter::Mesh::Peer.new(name: NODE_A[:name], url: NODE_A[:url], capabilities: NODE_A[:capabilities].map(&:to_sym))
+Igniter::Cluster::Mesh.config.peer_registry.register(
+  Igniter::Cluster::Mesh::Peer.new(name: NODE_A[:name], url: NODE_A[:url], capabilities: NODE_A[:capabilities].map(&:to_sym))
 )
 
 puts "\nC's registry before gossip:"
-Igniter::Mesh.config.peer_registry.all.each do |p|
+Igniter::Cluster::Mesh.config.peer_registry.all.each do |p|
   puts "  - #{p.name} @ #{p.url} caps=#{p.capabilities}"
 end
 
-knows_b_before = !Igniter::Mesh.config.peer_registry.peer_named("node-b").nil?
+knows_b_before = !Igniter::Cluster::Mesh.config.peer_registry.peer_named("node-b").nil?
 puts "  C knows node-b? #{knows_b_before}"
 puts
 
@@ -109,14 +111,14 @@ puts "=" * 60
 puts "Scenario 2: C runs one gossip round → discovers B via A"
 puts "=" * 60
 
-Igniter::Mesh::GossipRound.new(Igniter::Mesh.config).run
+Igniter::Cluster::Mesh::GossipRound.new(Igniter::Cluster::Mesh.config).run
 
 puts "\nC's registry after gossip:"
-Igniter::Mesh.config.peer_registry.all.each do |p|
+Igniter::Cluster::Mesh.config.peer_registry.all.each do |p|
   puts "  - #{p.name} @ #{p.url} caps=#{p.capabilities}"
 end
 
-knows_b_after = !Igniter::Mesh.config.peer_registry.peer_named("node-b").nil?
+knows_b_after = !Igniter::Cluster::Mesh.config.peer_registry.peer_named("node-b").nil?
 puts "\n  C knows node-b? #{knows_b_after}"
 puts "  Convergence achieved without seed: #{knows_b_after}"
 puts
@@ -128,9 +130,9 @@ puts "=" * 60
 puts "Scenario 3: gossip_fanout = 0 disables the gossip round"
 puts "=" * 60
 
-Igniter::Mesh.reset!
+Igniter::Cluster::Mesh.reset!
 
-Igniter::Mesh.configure do |c|
+Igniter::Cluster::Mesh.configure do |c|
   c.peer_name          = NODE_C[:name]
   c.local_url          = NODE_C[:url]
   c.gossip_fanout      = 0   # disabled
@@ -139,13 +141,13 @@ Igniter::Mesh.configure do |c|
 end
 
 # Seed registry with A
-Igniter::Mesh.config.peer_registry.register(
-  Igniter::Mesh::Peer.new(name: NODE_A[:name], url: NODE_A[:url], capabilities: NODE_A[:capabilities].map(&:to_sym))
+Igniter::Cluster::Mesh.config.peer_registry.register(
+  Igniter::Cluster::Mesh::Peer.new(name: NODE_A[:name], url: NODE_A[:url], capabilities: NODE_A[:capabilities].map(&:to_sym))
 )
 
-before_size = Igniter::Mesh.config.peer_registry.size
-Igniter::Mesh::Poller.new(Igniter::Mesh.config).poll_once  # no seeds → no seed fetch; gossip disabled
-after_size  = Igniter::Mesh.config.peer_registry.size
+before_size = Igniter::Cluster::Mesh.config.peer_registry.size
+Igniter::Cluster::Mesh::Poller.new(Igniter::Cluster::Mesh.config).poll_once  # no seeds → no seed fetch; gossip disabled
+after_size  = Igniter::Cluster::Mesh.config.peer_registry.size
 
 puts "  gossip_fanout = 0 → registry size unchanged: #{before_size} → #{after_size}"
 puts
@@ -153,7 +155,7 @@ puts
 # ─────────────────────────────────────────────────────────────────────────────
 # Cleanup
 # ─────────────────────────────────────────────────────────────────────────────
-Igniter::Mesh.reset!
+Igniter::Cluster::Mesh.reset!
 
 Igniter::Server::Client.class_eval do
   alias_method :list_peers, :real_list_peers_gossip

data/examples/reactive_auditing.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/extensions/auditing"
+require "igniter/extensions/reactive"
+
+EFFECT_VALUES = []
+INVALIDATIONS = []
+
+class ReactiveAuditQuoteContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :vat_rate, with: :country do |country:|
+      country == "UA" ? 0.2 : 0.0
+    end
+
+    compute :gross_total, with: %i[order_total vat_rate] do |order_total:, vat_rate:|
+      (order_total * (1 + vat_rate)).round(2)
+    end
+
+    expose :gross_total, as: :response
+  end
+
+  react_to :node_invalidated, path: "gross_total" do |event:, **|
+    INVALIDATIONS << event.payload[:cause]
+  end
+
+  effect "gross_total" do |value:, **|
+    EFFECT_VALUES << value
+  end
+end
+
+contract = ReactiveAuditQuoteContract.new(order_total: 100, country: "UA")
+
+puts "first_response=#{contract.result.response}"
+
+contract.update_inputs(order_total: 150)
+puts "second_response=#{contract.result.response}"
+
+snapshot = contract.audit_snapshot
+event_types = snapshot[:events].map { |event| event[:type] }.uniq
+
+puts "effect_values=#{EFFECT_VALUES.inspect}"
+puts "invalidations=#{INVALIDATIONS.inspect}"
+puts "event_types=#{event_types.inspect}"
+puts "gross_total_state=#{snapshot[:states][:gross_total].slice(:status, :value).inspect}"
+puts "event_count=#{snapshot[:event_count]}"

data/examples/run.rb

@@ -0,0 +1,163 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+require "timeout"
+
+require_relative "catalog"
+
+module IgniterExamples
+  class Runner
+    Result = Struct.new(
+      :example,
+      :status,
+      :stdout,
+      :stderr,
+      :exit_status,
+      :elapsed,
+      :reason,
+      keyword_init: true
+    ) do
+      def ok?
+        status == :passed
+      end
+    end
+
+    def run(example, extra_args: nil)
+      unless example.runnable?
+        return Result.new(example: example, status: :skipped, reason: example.skip_reason)
+      end
+
+      argv = extra_args.nil? ? example.command_args : extra_args
+      if !example.autonomous? && argv.empty?
+        return Result.new(example: example, status: :skipped, reason: example.skip_reason)
+      end
+
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      stdout = +""
+      stderr = +""
+      exit_status = nil
+
+      Timeout.timeout(example.timeout) do
+        stdout, stderr, process_status = Open3.capture3(
+          RbConfig.ruby,
+          example.full_path,
+          *argv
+        )
+        exit_status = process_status.exitstatus
+      end
+
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+      failure_reason = validate_output(example, stdout, exit_status)
+      status = failure_reason ? :failed : :passed
+
+      Result.new(
+        example: example,
+        status: status,
+        stdout: stdout,
+        stderr: stderr,
+        exit_status: exit_status,
+        elapsed: elapsed,
+        reason: failure_reason
+      )
+    rescue Timeout::Error
+      Result.new(
+        example: example,
+        status: :failed,
+        stdout: stdout,
+        stderr: stderr,
+        exit_status: nil,
+        elapsed: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at,
+        reason: "timed out after #{example.timeout}s"
+      )
+    end
+
+    private
+
+    def validate_output(example, stdout, exit_status)
+      return "exited with status #{exit_status}" unless exit_status == 0
+
+      missing = Array(example.expected_fragments).reject { |fragment| stdout.include?(fragment) }
+      return nil if missing.empty?
+
+      "missing expected output: #{missing.first.inspect}"
+    end
+  end
+end
+
+def print_usage
+  puts "Usage:"
+  puts "  ruby examples/run.rb list"
+  puts "  ruby examples/run.rb smoke"
+  puts "  ruby examples/run.rb all"
+  puts "  ruby examples/run.rb run <example> [example args...]"
+end
+
+def print_list
+  IgniterExamples.all.each do |example|
+    suffix = example.skip_reason ? " (#{example.skip_reason})" : ""
+    puts "#{example.status.to_s.ljust(11)} #{example.id.ljust(24)} #{example.summary}#{suffix}"
+  end
+end
+
+def print_result(result)
+  label = result.status.to_s.upcase.ljust(7)
+  timing = result.elapsed ? format("%0.2fs", result.elapsed) : "--"
+  line = "#{label} #{result.example.id.ljust(24)} #{timing}"
+  line += "  #{result.reason}" if result.reason
+  puts line
+
+  return unless result.status == :failed
+
+  unless result.stderr.to_s.empty?
+    first_error = result.stderr.lines.first.to_s.strip
+    puts "        stderr: #{first_error}" unless first_error.empty?
+  end
+end
+
+def run_examples(examples, extra_args: nil)
+  runner = IgniterExamples::Runner.new
+  results = examples.map do |example|
+    runner.run(example, extra_args: extra_args)
+  end
+
+  results.each { |result| print_result(result) }
+
+  passed = results.count(&:ok?)
+  failed = results.count { |result| result.status == :failed }
+  skipped = results.count { |result| result.status == :skipped }
+
+  puts
+  puts "Summary: #{passed} passed, #{failed} failed, #{skipped} skipped"
+
+  exit(failed.zero? ? 0 : 1)
+end
+
+command = ARGV.shift || "smoke"
+
+case command
+when "list"
+  print_list
+when "smoke"
+  run_examples(IgniterExamples.smoke)
+when "all"
+  run_examples(IgniterExamples.all)
+when "run"
+  name = ARGV.shift
+  unless name
+    print_usage
+    exit 1
+  end
+
+  example = IgniterExamples.find(name)
+  unless example
+    warn "Unknown example: #{name}"
+    exit 1
+  end
+
+  run_examples([example], extra_args: ARGV)
+else
+  print_usage
+  exit 1
+end

data/lib/igniter/monorepo_packages.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+[
+  File.expand_path("../../packages/igniter-core/lib", __dir__),
+  File.expand_path("../../packages/igniter-agents/lib", __dir__),
+  File.expand_path("../../packages/igniter-ai/lib", __dir__),
+  File.expand_path("../../packages/igniter-sdk/lib", __dir__),
+  File.expand_path("../../packages/igniter-extensions/lib", __dir__),
+  File.expand_path("../../packages/igniter-app/lib", __dir__),
+  File.expand_path("../../packages/igniter-server/lib", __dir__),
+  File.expand_path("../../packages/igniter-cluster/lib", __dir__),
+  File.expand_path("../../packages/igniter-rails/lib", __dir__),
+  File.expand_path("../../packages/igniter-frontend/lib", __dir__),
+  File.expand_path("../../packages/igniter-schema-rendering/lib", __dir__)
+].each do |path|
+  $LOAD_PATH.unshift(path) if File.directory?(path) && !$LOAD_PATH.include?(path)
+end

data/lib/igniter/stack.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "monorepo_packages"
+require "igniter/sdk"
+require "igniter/app/stack_pack"