igniter 0.4.5 → 0.5.1

data/packages/igniter-core/lib/igniter/core/tool.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "runtime/deferred_result"
+require_relative "executor"
+
+module Igniter
+  # Base class for AI-callable tools.
+  #
+  # Extends +Igniter::Executor+ with declarative metadata for LLM function-calling
+  # (Anthropic, OpenAI) and capability-based access guards.
+  # Shares the discovery DSL with +Igniter::AI::Skill+ via +Tool::Discoverable+.
+  #
+  # == Defining a tool
+  #
+  #   class SearchWeb < Igniter::Tool
+  #     description "Search the internet for current information"
+  #
+  #     param :query,       type: :string,  required: true,  desc: "The search query"
+  #     param :max_results, type: :integer, default: 5,      desc: "Max results to return"
+  #
+  #     requires_capability :web_access
+  #
+  #     def call(query:, max_results: 5)
+  #       [{ title: "...", url: "...", snippet: "..." }]
+  #     end
+  #   end
+  #
+  # == Schema generation
+  #
+  #   SearchWeb.tool_name             # => "search_web"
+  #   SearchWeb.to_schema             # => { name:, description:, parameters: { ... } }
+  #   SearchWeb.to_schema(:anthropic) # => { name:, description:, input_schema: { ... } }
+  #   SearchWeb.to_schema(:openai)    # => { type: "function", function: { ... } }
+  #
+  # == Compatibility
+  #
+  # Tool inherits +Igniter::Executor+ — usable as a compute node in any Contract graph.
+  class Tool < Executor
+    # Raised when a tool or skill requires a capability the calling agent does not have.
+    # Also aliased as +Igniter::AI::Skill::CapabilityError+.
+    class CapabilityError < Igniter::Error; end
+
+    require_relative "tool/discoverable"
+    include Discoverable
+
+    def self.inherited(subclass)
+      super
+      # Tool subclasses always start with empty params and capabilities —
+      # each concrete tool declares its own. Only the description carries forward.
+      subclass.instance_variable_set(:@tool_params, [])
+      subclass.instance_variable_set(:@required_capabilities, [].freeze)
+      subclass.instance_variable_set(:@tool_description, @tool_description)
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Igniter
-  VERSION = "0.4.5"
+  VERSION = "0.5.1"
 end

data/packages/igniter-core/lib/igniter/core.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "core/version"
+require_relative "core/errors"
+require_relative "core/type_system"
+require_relative "core/executor"
+require_relative "core/executor_registry"
+require_relative "core/effect"
+require_relative "core/effect_registry"
+require_relative "core/model"
+require_relative "core/compiler"
+require_relative "core/events"
+require_relative "core/runtime"
+require_relative "core/dto"
+require_relative "core/dsl"
+require_relative "core/extensions"
+require_relative "core/diagnostics"
+require_relative "core/contract"
+require_relative "core/stream_loop"
+require_relative "core/tool"
+
+module Igniter
+end

data/packages/igniter-core/lib/igniter-core.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/core"

data/packages/igniter-extensions/README.md

@@ -0,0 +1,21 @@
+# igniter-extensions
+
+Public extension entrypoints for Igniter.
+
+This package owns the `igniter/extensions/*` activation surface, including:
+
+- `require "igniter/extensions/dataflow"`
+- `require "igniter/extensions/saga"`
+- `require "igniter/extensions/provenance"`
+- `require "igniter/extensions/differential"`
+- `require "igniter/extensions/incremental"`
+
+It also provides the package facade:
+
+- `require "igniter-extensions"`
+
+Docs:
+
+- [Guide](../../docs/guide/README.md)
+- [Core guide](../../docs/guide/core.md)
+- [Dev](../../docs/dev/README.md)

data/packages/igniter-extensions/lib/igniter/extensions/auditing.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "igniter/core/extensions/auditing"

data/packages/igniter-extensions/lib/igniter/extensions/capabilities.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "igniter/core/capabilities"
+
+# Patches CompiledGraph with capability introspection methods.
+# The Resolver integration is handled via guard-claused hooks in resolver.rb.
+module Igniter
+  module Compiler
+    class CompiledGraph
+      # Returns a Hash of { node_name => [capabilities] } for every compute/effect
+      # node whose executor declares at least one capability.
+      def required_capabilities
+        (nodes + outputs).each_with_object({}) do |node, memo|
+          caps = node_capabilities(node)
+          memo[node.name] = caps unless caps.empty?
+        end
+      end
+
+      # Returns declared capabilities for a single node by name.
+      def capabilities_for(node_name)
+        sym    = node_name.to_sym
+        target = (nodes + outputs).find { |n| n.name == sym }
+        return [] unless target
+
+        node_capabilities(target)
+      end
+
+      private
+
+      def node_capabilities(node)
+        callable = node.respond_to?(:callable) ? node.callable : nil
+        callable ||= node.respond_to?(:adapter_class) ? node.adapter_class : nil
+        return [] unless callable.is_a?(Class) && callable <= Igniter::Executor
+
+        callable.declared_capabilities
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/content_addressing.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Loading this file activates content-addressed caching for pure executors.
+# The Resolver picks up content addressing via a guard clause when this constant is defined.
+require "igniter/core/content_addressing"

data/packages/igniter-extensions/lib/igniter/extensions/dataflow.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/core/dataflow"
+
+# Activates incremental dataflow support for all contracts.
+#
+# After requiring this file:
+#
+#   - `collection` DSL accepts `mode: :incremental` and `window:` options.
+#   - Contracts gain `#feed_diff` — push event-style diffs instead of full arrays.
+#   - Contracts gain `#collection_diff` — inspect what changed after the last resolve.
+#
+# == Usage
+#
+#   require "igniter/extensions/dataflow"
+#
+#   class SensorPipeline < Igniter::Contract
+#     define do
+#       input :readings, type: :array
+#
+#       collection :processed,
+#                  with: :readings,
+#                  each: SensorContract,
+#                  key: :sensor_id,
+#                  mode: :incremental,
+#                  window: { last: 500 }
+#
+#       output :processed
+#     end
+#   end
+#
+#   contract = SensorPipeline.new(readings: initial_readings)
+#   contract.resolve_all
+#
+#   # Push new events without replacing the full array
+#   contract.feed_diff(:readings, add: [new_reading], remove: [:sensor_old])
+#   contract.resolve_all
+#
+#   # Inspect what changed
+#   diff = contract.collection_diff(:processed)
+#   diff.added     # => [:sensor_42]
+#   diff.removed   # => [:sensor_old]
+#   diff.changed   # => []
+#   diff.unchanged # => [:sensor_1, :sensor_2, ...]
+#
+module Igniter
+  module Extensions
+    module Dataflow
+      module InstanceMethods
+        # Push a diff to a collection input without replacing the full array.
+        #
+        # Automatically finds the incremental collection node that uses +input_name+
+        # as its source dependency, uses its key_name to merge the diff into the
+        # current input array, then calls update_inputs.
+        #
+        # @param input_name [Symbol, String]  the contract input holding the collection
+        # @param add        [Array<Hash>]     new items to append
+        # @param remove     [Array]           keys or Hash items to remove (matched by key_name)
+        # @param update     [Array<Hash>]     updated versions of existing items (replace by key)
+        # @return [self]
+        #
+        # @raise [ArgumentError] if no incremental collection node uses the given input
+        def feed_diff(input_name, add: [], remove: [], update: [])
+          sym      = input_name.to_sym
+          key_name = _incremental_node_for(sym).key_name
+          current  = execution.inputs[sym].dup || []
+          items    = _apply_diff(current, key_name, add: add, remove: remove, update: update)
+          execution.update_inputs(sym => items)
+          self
+        end
+
+        # Returns the Diff from the last resolve for a named collection node.
+        #
+        # @param collection_name [Symbol, String]  the collection node name
+        # @return [Igniter::Dataflow::Diff, nil]  nil if not yet resolved or not incremental
+        def collection_diff(collection_name)
+          state = execution.cache.fetch(collection_name.to_sym)
+          value = state&.value
+          value.respond_to?(:diff) ? value.diff : nil
+        end
+
+        private
+
+        def _apply_diff(items, key_name, add:, remove:, update:)
+          remove_keys = Array(remove).map { |e| e.is_a?(Hash) ? e.fetch(key_name) : e }.to_set
+          result = items.reject { |item| remove_keys.include?(item.fetch(key_name)) }
+          _apply_updates(result, key_name, update)
+          result.concat(Array(add))
+        end
+
+        def _apply_updates(items, key_name, updates)
+          Array(updates).each do |updated|
+            k   = updated.fetch(key_name)
+            idx = items.index { |item| item.fetch(key_name) == k }
+            idx ? items[idx] = updated : items << updated
+          end
+        end
+
+        def _incremental_node_for(input_name)
+          node = execution.compiled_graph.nodes.find do |n|
+            n.kind == :collection &&
+              n.mode == :incremental &&
+              n.source_dependency == input_name
+          end
+          return node if node
+
+          raise ArgumentError,
+                "No incremental collection node found for input '#{input_name}'. " \
+                "Ensure the collection is declared with mode: :incremental."
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Dataflow::InstanceMethods)

data/{lib → packages/igniter-extensions/lib}/igniter/extensions/differential.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "igniter"
-require "igniter/differential"
+require "igniter/core/differential"
 
 module Igniter
   module Extensions

data/{lib → packages/igniter-extensions/lib}/igniter/extensions/execution_report.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "igniter"
-require "igniter/execution_report"
+require "igniter/core/execution_report"
 
 module Igniter
   module Extensions

data/{lib → packages/igniter-extensions/lib}/igniter/extensions/incremental.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "igniter"
-require "igniter/incremental"
+require "igniter/core/incremental"
 
 module Igniter
   module Extensions

data/packages/igniter-extensions/lib/igniter/extensions/introspection.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "igniter/core/extensions/introspection"

data/packages/igniter-extensions/lib/igniter/extensions/invariants.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "igniter/core/extensions/invariants"

data/{lib → packages/igniter-extensions/lib}/igniter/extensions/provenance.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../provenance"
+require "igniter/core/provenance"
 
 module Igniter
   module Extensions

data/packages/igniter-extensions/lib/igniter/extensions/reactive.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "igniter/core/extensions/reactive"

data/{lib → packages/igniter-extensions/lib}/igniter/extensions/saga.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "igniter"
-require "igniter/saga"
+require "igniter/core/saga"
 
 module Igniter
   module Extensions

data/packages/igniter-extensions/lib/igniter/extensions.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "igniter"
+
+module Igniter
+  module Extensions
+  end
+end

data/packages/igniter-extensions/lib/igniter-extensions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/extensions"

data/packages/igniter-frontend/README.md

@@ -0,0 +1,224 @@
+# igniter-frontend
+
+`igniter-frontend` is a local monorepo gem for developer-facing app web surfaces on top of Igniter.
+
+It now ships with `arbre` as a standard dependency. The intent is simple:
+
+- `Igniter Frontend` should feel as simple and powerful for Ruby-authored app UI
+  as `ActiveAdmin` feels for admin UI
+- Arbre is no longer a side adapter you add by hand later
+- Arbre is part of the default developer-authoring lane for `igniter-frontend`
+
+It groups high-level concerns that belong together in app development:
+
+- route authoring
+- handler/controller lifecycle
+- request/response helpers
+- mounted-app aware contexts
+- Arbre page rendering
+- semantic Arbre components
+- optional JavaScript runtime and app-owned entrypoints
+
+Schema-driven agent rendering intentionally lives outside this package. Use a
+separate package for that lane so the human-first app surface stays simple.
+
+The goal is not to re-create Rails.
+The goal is to give Igniter apps a small, coherent, HTML-first framework for
+building dashboards, chats, operator tools, decentralized personal apps, and
+other rich mounted web surfaces.
+
+The frontend direction is now explicitly:
+
+- Arbre for developer-authored page composition
+- Tailwind surfaces for shared UI language
+- stronger UX/UI semantics on top of that Arbre lane over time
+
+That “stronger semantics” line now includes richer Arbre primitives such as:
+
+- `badge` with inferred status tone and compact sizing
+- `card#line` with `as: :badge` / `as: :code`
+- placeholder-aware schema rows and nested `subcard` composition
+- `table_with` for logs, events, history, and other collection-heavy operator views
+- `viz` for raw hashes, arrays, objects, and runtime payload inspection
+- `filters` for mounted-safe search and narrowing lanes above tables and feeds
+- `pagination` for mounted-safe browsing lanes across notes, history, logs, and other long collections
+- `sidebar_shell` for app-level operator/admin navigation and stable content chrome
+- `breadcrumbs` for compact in-app location trails above operator/admin content
+- semantic value primitives such as `boolean`, `datetime`, `indicator`, `number`, and `percentage`
+- state primitives such as `empty_state` and `loading_state`
+- `shell_columns` for main/aside dashboard composition inside an app shell
+
+Authoring guide:
+
+- [Frontend Authoring](../../docs/guide/frontend-authoring.md)
+- [Frontend Components](../../docs/guide/frontend-components.md)
+- [Guide](../../docs/guide/README.md)
+- [Dev](../../docs/dev/README.md)
+
+## First-cut API
+
+```ruby
+require "igniter/app"
+require "igniter-frontend"
+
+class WebApp < Igniter::App
+  include Igniter::Frontend::App
+
+  root_dir __dir__
+  config_file "app.yml"
+  frontend_assets path: "frontend"
+
+  get "/", to: Web::Handlers::HomeHandler
+
+  scope "/notes" do
+    post "/", to: Web::Handlers::NotesCreateHandler
+  end
+end
+```
+
+```ruby
+module Web
+  module Handlers
+    class HomeHandler < Igniter::Frontend::Handler
+      def call
+        render Views::HomePage,
+               context: build_context(Contexts::HomeContext, title: "Home")
+      end
+    end
+  end
+end
+```
+
+```ruby
+module Web
+  module Views
+    class HomePage < Igniter::Frontend::ArbrePage
+      template_root __dir__
+      template "home"
+      layout "layout"
+
+      def initialize(context:)
+        @context = context
+      end
+
+      def template_locals
+        { page_context: @context }
+      end
+    end
+  end
+end
+```
+
+## Status
+
+This package now owns the human-facing web surface directly inside the monorepo:
+
+- route DSL and handler lifecycle
+- HTML builder/page abstractions
+- Arbre page pipeline
+- Tailwind shell and semantic UI components
+- optional frontend JavaScript runtime with app-owned assets under `frontend/`
+
+It is no longer just a facade over `lib/igniter/plugins/view`.
+
+## Optional JavaScript
+
+Use `frontend_assets` when the app wants a small built-in runtime plus its own
+JavaScript entrypoints.
+
+```ruby
+class DashboardApp < Igniter::App
+  include Igniter::Frontend::App
+
+  root_dir __dir__
+  frontend_assets path: "frontend"
+end
+```
+
+App structure:
+
+```text
+apps/dashboard/
+  app.rb
+  frontend/
+    application.js
+    controllers/
+```
+
+Layout usage:
+
+```ruby
+body do
+  render_template_content
+  render_frontend_javascript "application"
+end
+```
+
+This serves:
+
+- built-in runtime at `/__frontend/runtime.js`
+- app entrypoints like `/__frontend/assets/application.js`
+
+Both URLs stay mounted-app aware when rendered through `ArbrePage` helpers.
+
+Built-in controllers currently include:
+
+- `tabs` for semantic tab panels
+- `stream` for `EventSource` lifecycle, JSON parsing, and app-level hooks
+
+Example stream wiring:
+
+```ruby
+main(
+  "data-ig-controller": "stream",
+  "data-ig-stream-url-value": page_context.route("/api/overview/stream"),
+  "data-ig-stream-events-value": "[\"overview\",\"activity\"]",
+  "data-ig-stream-hook-value": "homeLabOverviewStream"
+) do
+  render_template_content
+end
+```
+
+```js
+window.homeLabOverviewStream = {
+  overview({ controller, payload }) {
+    controller.setTextTarget("generatedAt", payload.generated_at);
+  }
+};
+```
+
+For repeated updates, prefer marking DOM zones with `data-ig-stream-target` and
+using the small helpers exposed by `stream`:
+
+- `setTextTarget(name, value)`
+- `setHtmlTarget(name, html)`
+- `setJsonTarget(name, payload)`
+- `prependHtmlTarget(name, html, { limit: ... })`
+
+In Arbre pages and components, prefer the helper:
+
+```ruby
+span current_value, **stream_target(:generated_at, id: "generated-at")
+```
+
+That keeps `data-ig-*` details out of app templates.
+
+The same applies to controller values:
+
+```ruby
+main(
+  **stream_scope,
+  **stream_value(:url, page_context.route("/api/overview/stream")),
+  **stream_value(:events, %w[overview activity]),
+  **stream_value(:hook, "homeLabOverviewStream")
+) do
+  render_template_content
+end
+```
+
+Use `controller_value(:tabs, :active_id, "routing")` when you need the generic
+form outside the `stream` lane.
+
+For the controller name itself, prefer `stream_scope` or the generic
+`controller_scope(:stream, :operator_panel)` over raw `data-ig-controller`
+strings.

data/packages/igniter-frontend/lib/igniter/frontend/app.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Frontend
+    module App
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def frontend_assets(path: Assets::DEFAULT_SOURCE_PATH, mount: Assets::DEFAULT_MOUNT_PATH)
+          @frontend_assets_config = Assets.build_config(
+            root_dir: root_dir || Dir.pwd,
+            source_path: path,
+            mount_path: mount
+          )
+
+          route("GET", Assets.runtime_path(mount_path: @frontend_assets_config.fetch(:mount_path)), with: Assets.runtime_handler)
+          route(
+            "GET",
+            Assets.javascript_route_pattern(mount_path: @frontend_assets_config.fetch(:mount_path)),
+            with: Assets.javascript_handler(@frontend_assets_config)
+          )
+        end
+
+        def frontend_assets_config
+          @frontend_assets_config
+        end
+
+        def get(path, to: nil, with: nil, &block)
+          frontend_route("GET", path, to: to || with, &block)
+        end
+
+        def post(path, to: nil, with: nil, &block)
+          frontend_route("POST", path, to: to || with, &block)
+        end
+
+        def put(path, to: nil, with: nil, &block)
+          frontend_route("PUT", path, to: to || with, &block)
+        end
+
+        def patch(path, to: nil, with: nil, &block)
+          frontend_route("PATCH", path, to: to || with, &block)
+        end
+
+        def delete(path, to: nil, with: nil, &block)
+          frontend_route("DELETE", path, to: to || with, &block)
+        end
+
+        def scope(path, &block)
+          raise ArgumentError, "scope requires a block" unless block
+
+          current_frontend_scope_stack << path.to_s
+          instance_eval(&block)
+        ensure
+          current_frontend_scope_stack.pop
+        end
+
+        private
+
+        def frontend_route(method, path, to: nil, &block)
+          handler = to || block
+          raise ArgumentError, "#{method} #{path} requires `to:` or a block" unless handler
+
+          route(method, scoped_frontend_path(path), with: normalize_frontend_handler(handler))
+        end
+
+        def normalize_frontend_handler(handler)
+          return handler if handler.respond_to?(:call)
+
+          raise ArgumentError, "frontend route target must respond to #call"
+        end
+
+        def current_frontend_scope_stack
+          @frontend_scope_stack ||= []
+        end
+
+        def scoped_frontend_path(path)
+          segments = current_frontend_scope_stack + [path.to_s]
+          normalized = segments.join("/")
+          normalized = normalized.gsub(%r{/+}, "/")
+          normalized = "/#{normalized}" unless normalized.start_with?("/")
+          return "/" if normalized == "/"
+
+          normalized.sub(%r{/\z}, "")
+        end
+      end
+    end
+  end
+end