igniter 0.4.3 → 0.5.0

data/lib/igniter/application/generator.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Igniter
+  class Application
+    # Generates a new Igniter application scaffold.
+    # Invoked via: igniter-server new my_app
+    #
+    # Creates:
+    #   my_app/
+    #   ├── application.rb     — Application class (entry point)
+    #   ├── application.yml    — base config (port, log_format, etc.)
+    #   ├── Gemfile
+    #   ├── config.ru          — Rack entry point for Puma/Unicorn
+    #   ├── bin/start          — convenience start script
+    #   ├── contracts/         — Contract subclasses
+    #   ├── executors/         — Executor subclasses
+    #   └── agents/            — Agent, Supervisor, and ProactiveAgent subclasses
+    class Generator
+      def initialize(name)
+        @name = name.to_s.strip
+        raise ArgumentError, "App name cannot be blank" if @name.empty?
+
+        @dir = @name
+      end
+
+      def generate # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        create_dir ""
+        create_dir "contracts"
+        create_dir "executors"
+        create_dir "agents"
+        create_dir "bin"
+
+        write "application.rb",  application_rb
+        write "application.yml", application_yml
+        write "Gemfile",         gemfile
+        write "config.ru",       config_ru
+        write "bin/start",       bin_start
+        write "contracts/.keep", ""
+        write "executors/.keep", ""
+        write "agents/.keep",    ""
+
+        FileUtils.chmod(0o755, path("bin/start"))
+
+        puts
+        puts "Done! Next steps:"
+        puts "  cd #{@name}"
+        puts "  bundle install"
+        puts "  bin/start"
+        puts
+        puts "To run with Puma:"
+        puts "  bundle add puma"
+        puts "  bundle exec puma config.ru"
+      end
+
+      private
+
+      def path(rel) = File.join(@dir, rel)
+
+      def create_dir(rel)
+        full = rel.empty? ? @dir : path(rel)
+        FileUtils.mkdir_p(full)
+        puts "  create  #{full}/"
+      end
+
+      def write(rel, content)
+        full = path(rel)
+        File.write(full, content)
+        puts "  create  #{full}"
+      end
+
+      def module_name
+        @name.split(/[-_\s]+/).map(&:capitalize).join
+      end
+
+      def application_rb
+        <<~RUBY
+          # frozen_string_literal: true
+
+          $LOAD_PATH.unshift(File.join(__dir__, "../../lib")) if File.exist?("../../lib/igniter.rb")
+
+          require "igniter"
+          require "igniter/server"
+          require "igniter/application"
+          require "igniter/agents"
+
+          class #{module_name}App < Igniter::Application
+            config_file File.join(__dir__, "application.yml")
+
+            # Eagerly load all .rb files from these directories on startup.
+            executors_path "executors"
+            contracts_path "contracts"
+            agents_path    "agents"
+
+            configure do |c|
+              # Override YAML values here, e.g.:
+              # c.port  = ENV.fetch("PORT", 4567).to_i
+              # c.store = Igniter::Runtime::Stores::MemoryStore.new
+            end
+
+            # Register contracts for HTTP dispatch:
+            # register "MyContract", MyContract
+
+            # Recurring background jobs:
+            # schedule :heartbeat, every: "30s" do
+            #   puts "[heartbeat] \#{Time.now.strftime("%H:%M:%S")}"
+            # end
+          end
+
+          #{module_name}App.start if $PROGRAM_NAME == __FILE__
+        RUBY
+      end
+
+      def application_yml
+        <<~YAML
+          server:
+            port: 4567
+            host: "0.0.0.0"
+            log_format: text   # text | json  (json = Loki/ELK compatible)
+            drain_timeout: 30  # seconds to wait for in-flight requests on shutdown
+        YAML
+      end
+
+      def gemfile
+        <<~RUBY
+          # frozen_string_literal: true
+
+          source "https://rubygems.org"
+
+          gem "igniter"
+        RUBY
+      end
+
+      def config_ru
+        <<~RUBY
+          # frozen_string_literal: true
+          # Rack entry point — use with Puma or any Rack-compatible server.
+          #   bundle exec puma config.ru
+
+          require_relative "application"
+
+          run #{module_name}App.rack_app
+        RUBY
+      end
+
+      def bin_start
+        <<~BASH
+          #!/usr/bin/env bash
+          set -e
+          cd "$(dirname "$0")/.."
+          exec bundle exec ruby application.rb "$@"
+        BASH
+      end
+    end
+  end
+end

data/lib/igniter/application/scheduler.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Application
+    # Lightweight pure-Ruby scheduler for recurring background jobs.
+    # Uses one Thread per job — no external dependencies.
+    #
+    # Usage:
+    #   s = Scheduler.new
+    #   s.add :cleanup, every: "1h" do ... end
+    #   s.add :report,  every: "1d", at: "09:00" do ... end
+    #   s.start
+    #   # later:
+    #   s.stop
+    #
+    # Interval formats accepted by `every:`:
+    #   Integer / Float  — seconds
+    #   "30s"            — 30 seconds
+    #   "5m"             — 5 minutes
+    #   "2h"             — 2 hours
+    #   "1d"             — 1 day
+    #   { hours: 1, minutes: 30 }
+    class Scheduler
+      Job = Data.define(:name, :interval, :at_time, :block)
+
+      def initialize(logger: nil)
+        @jobs    = []
+        @threads = []
+        @logger  = logger
+        @mu      = Mutex.new
+        @running = false
+      end
+
+      def add(name, every:, at: nil, &block)
+        @jobs << Job.new(
+          name: name.to_sym,
+          interval: parse_interval(every),
+          at_time: at,
+          block: block
+        )
+      end
+
+      def start
+        @mu.synchronize { @running = true }
+        @jobs.each { |job| @threads << Thread.new { run_job(job) } }
+        self
+      end
+
+      def stop
+        @mu.synchronize { @running = false }
+        @threads.each(&:kill)
+        @threads.clear
+      end
+
+      def job_names
+        @jobs.map(&:name)
+      end
+
+      private
+
+      def run_job(job)
+        sleep initial_delay(job)
+        loop do
+          break unless @mu.synchronize { @running }
+
+          begin
+            job.block.call
+          rescue => e # rubocop:disable Style/RescueStandardError
+            @logger&.error("Scheduler job failed", name: job.name, error: e.message)
+          end
+
+          sleep job.interval
+        end
+      end
+
+      # If `at:` is given (e.g. "09:00"), delay until the next occurrence of that time.
+      def initial_delay(job)
+        return 0 unless job.at_time
+
+        h, m   = job.at_time.split(":").map(&:to_i)
+        now    = Time.now
+        target = Time.new(now.year, now.month, now.day, h, m, 0)
+        target += 86_400 if target <= now
+        target - now
+      end
+
+      def parse_interval(val) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity
+        case val
+        when Integer, Float then val.to_f
+        when String
+          case val
+          when /\A(\d+)s\z/i then Regexp.last_match(1).to_f
+          when /\A(\d+)m\z/i then Regexp.last_match(1).to_f * 60
+          when /\A(\d+)h\z/i then Regexp.last_match(1).to_f * 3600
+          when /\A(\d+)d\z/i then Regexp.last_match(1).to_f * 86_400
+          else raise ArgumentError, "Unknown interval: #{val.inspect} (use 30s / 5m / 2h / 1d)"
+          end
+        when Hash
+          val.fetch(:seconds, 0) +
+            val.fetch(:minutes, 0) * 60 +
+            val.fetch(:hours, 0) * 3600 +
+            val.fetch(:days, 0) * 86_400
+        else
+          raise ArgumentError, "Interval must be Integer, String, or Hash; got #{val.class}"
+        end
+      end
+    end
+  end
+end

data/lib/igniter/application/yml_loader.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Igniter
+  class Application
+    # Loads an application.yml and applies values to an AppConfig.
+    # YAML is loaded BEFORE the Ruby configure block, so blocks always win.
+    #
+    # Supported YAML structure:
+    #   server:
+    #     port: 4567
+    #     host: "0.0.0.0"
+    #     log_format: json        # "text" or "json"
+    #     drain_timeout: 30
+    class YmlLoader
+      # Maps [section, key] paths in YAML to AppConfig setters.
+      MAPPINGS = {
+        %w[server port] => ->(cfg, v) { cfg.port = Integer(v) },
+        %w[server host] => ->(cfg, v) { cfg.host = v.to_s },
+        %w[server log_format] => ->(cfg, v) { cfg.log_format = v.to_sym },
+        %w[server drain_timeout] => ->(cfg, v) { cfg.drain_timeout = Integer(v) }
+      }.freeze
+
+      def self.load(path)
+        return {} unless File.exist?(path.to_s)
+
+        YAML.safe_load(File.read(path)) || {}
+      end
+
+      def self.apply(config, yml)
+        MAPPINGS.each do |keys, setter|
+          value = yml.dig(*keys)
+          setter.call(config, value) unless value.nil?
+        end
+      end
+    end
+  end
+end

data/lib/igniter/application.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "igniter/server"
+require_relative "application/app_config"
+require_relative "application/yml_loader"
+require_relative "application/autoloader"
+require_relative "application/scheduler"
+require_relative "application/generator"
+
+module Igniter
+  # Base class for Igniter applications.
+  #
+  # Provides a unified DSL for configuration, contract registration,
+  # scheduled jobs, and server startup — replacing the raw
+  # Igniter::Server.configure boilerplate.
+  #
+  # == Minimal example
+  #
+  #   require "igniter/application"
+  #
+  #   class MyApp < Igniter::Application
+  #     config_file "application.yml"        # optional YAML base config
+  #
+  #     configure do |c|
+  #       c.port  = 4567
+  #       c.store = Igniter::Runtime::Stores::MemoryStore.new
+  #     end
+  #
+  #     register "OrderContract", OrderContract
+  #
+  #     schedule :cleanup, every: "1h" do
+  #       puts "running cleanup..."
+  #     end
+  #   end
+  #
+  #   MyApp.start       # blocking built-in HTTP server
+  #   MyApp.rack_app    # Rack-compatible app (Puma / Unicorn)
+  #
+  # == YAML config (application.yml)
+  #
+  #   server:
+  #     port: 4567
+  #     host: "0.0.0.0"
+  #     log_format: json    # text (default) or json
+  #     drain_timeout: 30
+  #
+  # Values from the YAML file are applied first; the Ruby `configure` block
+  # runs afterwards and always wins.
+  class Application
+    class << self
+      # ─── DSL ─────────────────────────────────────────────────────────────────
+
+      # Path to an optional YAML configuration file.
+      # Loaded before the configure block — configure values override YAML.
+      def config_file(path)
+        @yml_path = path
+      end
+
+      # Configure the application. Block receives an AppConfig instance.
+      # May be called multiple times; blocks are applied in order.
+      def configure(&block)
+        @configure_blocks << block
+      end
+
+      # Declare a directory whose .rb files are eagerly required at startup
+      # (before contracts are registered).
+      def executors_path(path)
+        @executors_paths << path
+      end
+
+      # Declare a directory whose .rb files are eagerly required at startup.
+      def contracts_path(path)
+        @contracts_paths << path
+      end
+
+      # Declare a directory whose .rb files are eagerly required at startup
+      # (agents, supervisors, and other actor-system components).
+      def agents_path(path)
+        @agents_paths << path
+      end
+
+      # Register a contract class under a name for HTTP dispatch.
+      def register(name, contract_class)
+        @registered[name.to_s] = contract_class
+      end
+
+      # Define a recurring background job.
+      #
+      #   schedule :report, every: "1d", at: "09:00" do
+      #     DailyReportContract.new.resolve_all(...)
+      #   end
+      #
+      # Interval formats: Integer (seconds), "30s", "5m", "2h", "1d",
+      # or Hash { hours: 1, minutes: 30 }.
+      def schedule(name, every:, at: nil, &block)
+        @scheduled_jobs << { name: name, every: every, at: at, block: block }
+      end
+
+      # ─── Lifecycle ───────────────────────────────────────────────────────────
+
+      # Start the built-in HTTP server (blocking).
+      # Schedules background jobs and registers an at_exit cleanup.
+      def start
+        sc    = build!
+        sched = build_scheduler(sc)
+        sched&.start
+        at_exit { sched&.stop }
+        Igniter::Server::HttpServer.new(sc).start
+      end
+
+      # Return a Rack-compatible application (for Puma / Unicorn / etc.).
+      def rack_app
+        sc = build!
+        build_scheduler(sc)&.start
+        Igniter::Server::RackApp.new(sc)
+      end
+
+      # Expose the AppConfig (populated after the first build!).
+      def config = @app_config
+
+      # ─── Inheritance isolation ────────────────────────────────────────────────
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@yml_path,         nil)
+        subclass.instance_variable_set(:@configure_blocks, [])
+        subclass.instance_variable_set(:@executors_paths,  [])
+        subclass.instance_variable_set(:@contracts_paths,  [])
+        subclass.instance_variable_set(:@agents_paths,     [])
+        subclass.instance_variable_set(:@registered,       {})
+        subclass.instance_variable_set(:@scheduled_jobs,   [])
+        subclass.instance_variable_set(:@app_config,       AppConfig.new)
+        subclass.instance_variable_set(:@build_scheduler,  nil)
+      end
+
+      private
+
+      # Build and return a ready Server::Config.
+      def build!
+        cfg = @app_config
+        apply_yml!(cfg)
+        autoload_paths!
+        @configure_blocks.each { |b| b.call(cfg) }
+        sc = cfg.to_server_config
+        @registered.each { |name, klass| sc.register(name, klass) }
+        sc
+      end
+
+      def apply_yml!(cfg)
+        return unless @yml_path
+
+        yml = YmlLoader.load(@yml_path)
+        YmlLoader.apply(cfg, yml)
+      end
+
+      def autoload_paths!
+        loader = Autoloader.new(base_dir: Dir.pwd)
+        @executors_paths.each { |p| loader.load_path(p) }
+        @contracts_paths.each { |p| loader.load_path(p) }
+        @agents_paths.each    { |p| loader.load_path(p) }
+      end
+
+      def build_scheduler(server_config)
+        return nil if @scheduled_jobs.empty?
+
+        @build_scheduler ||= begin
+          sched = Scheduler.new(logger: server_config.logger)
+          @scheduled_jobs.each { |j| sched.add(j[:name], every: j[:every], at: j[:at], &j[:block]) }
+          sched
+        end
+      end
+    end
+  end
+end

data/lib/igniter/capabilities.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Capability-based security for Igniter executors.
+  #
+  # Executors declare what they are allowed to do via the `capabilities` DSL.
+  # A Policy can deny or audit specific capabilities at execution time.
+  #
+  # == Usage
+  #
+  #   require "igniter/extensions/capabilities"
+  #
+  #   class PaymentExecutor < Igniter::Executor
+  #     capabilities :network, :external_api
+  #   end
+  #
+  #   class TaxCalculator < Igniter::Executor
+  #     pure   # shorthand for capabilities :pure
+  #   end
+  #
+  #   # Inspect a contract's required capabilities:
+  #   MyContract.compiled_graph.required_capabilities
+  #   # => { payment: [:network, :external_api], tax: [:pure] }
+  #
+  #   # Enforce a policy:
+  #   Igniter::Capabilities.policy = Igniter::Capabilities::Policy.new(
+  #     denied: %i[network external_api]
+  #   )
+  module Capabilities
+    KNOWN = %i[pure network database filesystem external_api messaging queue cache].freeze
+
+    class CapabilityViolationError < Igniter::Error
+      def initialize(message, node_name: nil)
+        super(message, context: { node_name: node_name }.compact)
+      end
+    end
+
+    # Enforce capability rules at execution time.
+    #
+    # Options:
+    #   denied:  Array of capabilities that must NOT be used.
+    #   on_unknown: :warn | :ignore (default :ignore) — what to do with undeclared capabilities.
+    class Policy
+      def initialize(denied: [], on_unknown: :ignore)
+        @denied     = Array(denied).map(&:to_sym).freeze
+        @on_unknown = on_unknown
+      end
+
+      # Raise CapabilityViolationError if the executor uses a denied capability.
+      def check!(node_name, executor_class)
+        caps       = executor_class.declared_capabilities
+        violations = caps & @denied
+        return if violations.empty?
+
+        raise CapabilityViolationError.new(
+          "Node '#{node_name}' executor #{executor_class.name} " \
+          "uses denied capabilities: #{violations.join(", ")}",
+          node_name: node_name
+        )
+      end
+    end
+
+    class << self
+      # Global capability policy. nil = no enforcement (default).
+      attr_accessor :policy
+    end
+  end
+end

data/lib/igniter/compiler/validators/dependencies_validator.rb

@@ -19,6 +19,7 @@ module Igniter
             validate_composition_node!(node) if node.kind == :composition
             validate_branch_node!(node) if node.kind == :branch
             validate_collection_node!(node) if node.kind == :collection
+            validate_aggregate_node!(node)   if node.kind == :aggregate
 
             node.dependencies.each do |dependency_name|
               next if @context.dependency_resolvable?(dependency_name)
@@ -175,10 +176,12 @@ module Igniter
             raise @context.validation_error(node, "Collection '#{node.name}' references an uncompiled contract")
           end
 
-          unless %i[collect fail_fast].include?(node.mode)
-            raise @context.validation_error(node, "Collection '#{node.name}' mode must be `:collect` or `:fail_fast`")
+          unless %i[collect fail_fast incremental].include?(node.mode)
+            raise @context.validation_error(node, "Collection '#{node.name}' mode must be `:collect`, `:fail_fast`, or `:incremental`")
           end
 
+          validate_window_option!(node) if node.window
+
           child_input_names = node.contract_class.compiled_graph.nodes.select { |child_node| child_node.kind == :input }.map(&:name)
           return if child_input_names.include?(node.key_name)
 
@@ -187,6 +190,51 @@ module Igniter
             "Collection '#{node.name}' key '#{node.key_name}' must be a child contract input"
           )
         end
+
+        def validate_window_option!(node) # rubocop:disable Metrics/MethodLength
+          window = node.window
+          unless window.is_a?(Hash)
+            raise @context.validation_error(node, "Collection '#{node.name}' window: must be a Hash")
+          end
+
+          if window.key?(:last)
+            unless window[:last].is_a?(Integer) && window[:last].positive?
+              raise @context.validation_error(node, "Collection '#{node.name}' window: { last: } must be a positive Integer")
+            end
+          elsif window.key?(:seconds)
+            unless window.key?(:field)
+              raise @context.validation_error(node, "Collection '#{node.name}' window: { seconds: } requires a :field key")
+            end
+          else
+            raise @context.validation_error(node, "Collection '#{node.name}' window: must use :last or :seconds")
+          end
+        end
+
+        def validate_aggregate_node!(node)
+          source_sym = node.source_collection
+          source = @context.runtime_nodes.find { |n| n.name == source_sym }
+
+          unless source
+            raise @context.validation_error(
+              node,
+              "Aggregate '#{node.name}' references unknown collection '#{source_sym}'"
+            )
+          end
+
+          unless source.kind == :collection
+            raise @context.validation_error(
+              node,
+              "Aggregate '#{node.name}': source '#{source_sym}' must be a collection node, got :#{source.kind}"
+            )
+          end
+
+          return if source.mode == :incremental
+
+          raise @context.validation_error(
+            node,
+            "Aggregate '#{node.name}': source '#{source_sym}' must use mode: :incremental"
+          )
+        end
       end
     end
   end

data/lib/igniter/compiler/validators/remote_validator.rb

@@ -25,6 +25,8 @@ module Igniter
         private
 
         def validate_url!(node)
+          return if node.routing_mode != :static
+
           return if node.node_url.start_with?("http://", "https://")
 
           raise @context.validation_error(