textus 0.53.0 → 0.54.0

data/lib/textus/step/base.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    class Base
-      class << self
-        # The step kind is derived from class hierarchy.
-        def kind
-          return :fetch if defined?(Step::Fetch) && self <= Step::Fetch
-          return :transform if defined?(Step::Transform) && self <= Step::Transform
-          return :validate if defined?(Step::Validate) && self <= Step::Validate
-          return :observe if defined?(Step::Observe) && self <= Step::Observe
-
-          raise NotImplementedError.new("#{self} is not a known step kind")
-        end
-
-        # Required #call kwargs the loader validates against the subclass.
-        def required_kwargs = []
-
-        # Built-ins (and only built-ins) override the registered name when the
-        # Ruby class name can't carry it (e.g. "markdown-links").
-        def step_name(value = :__read__)
-          if value == :__read__
-            @step_name
-          else
-            @step_name = value.to_s
-          end
-        end
-      end
-
-      # Assigned by the loader/registry at registration time.
-      attr_accessor :name
-    end
-  end
-end

data/lib/textus/step/builtin/csv_fetch.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-require "csv"
-require "yaml"
-
-module Textus
-  module Step
-    module Builtin
-      class CsvFetch < Step::Fetch
-        step_name "csv"
-        def call(config:, args:, **)
-          _ = args
-          rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
-          { _meta: {}, body: YAML.dump(rows) }
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/builtin/ical_events_fetch.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Textus
-  module Step
-    module Builtin
-      class IcalEventsFetch < Step::Fetch
-        step_name "ical-events"
-        def call(config:, args:, **)
-          _ = args
-          events_list = []
-          current = nil
-          config["bytes"].to_s.each_line do |line|
-            line = line.strip
-            case line
-            when "BEGIN:VEVENT" then current = {}
-            when "END:VEVENT"
-              events_list << current if current
-              current = nil
-            when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
-              current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
-            end
-          end
-          { _meta: {}, body: YAML.dump(events_list) }
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/builtin/json_fetch.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "yaml"
-
-module Textus
-  module Step
-    module Builtin
-      class JsonFetch < Step::Fetch
-        step_name "json"
-        def call(config:, args:, **)
-          _ = args
-          { _meta: {}, body: YAML.dump(JSON.parse(config["bytes"].to_s)) }
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/builtin/markdown_links_fetch.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Textus
-  module Step
-    module Builtin
-      class MarkdownLinksFetch < Step::Fetch
-        step_name "markdown-links"
-        def call(config:, args:, **)
-          _ = args
-          links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
-            { "text" => text, "href" => href }
-          end
-          { _meta: {}, body: YAML.dump(links) }
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/builtin/rss_fetch.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require "rexml/document"
-require "yaml"
-
-module Textus
-  module Step
-    module Builtin
-      class RssFetch < Step::Fetch
-        step_name "rss"
-        def call(config:, args:, **)
-          _ = args
-          doc = REXML::Document.new(config["bytes"].to_s)
-          items = doc.elements.to_a("//item").map do |item|
-            {
-              "title" => item.elements["title"]&.text,
-              "link" => item.elements["link"]&.text,
-              "pubDate" => item.elements["pubDate"]&.text,
-            }
-          end
-          { _meta: {}, body: YAML.dump(items) }
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/builtin.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Registers the framework-provided fetch steps (json/csv/markdown-links/
-    # ical-events/rss) into a registry at Store construction. The successor to
-    # Step::Builtin.register_all.
-    module Builtin
-      STEPS = [
-        JsonFetch, CsvFetch, MarkdownLinksFetch, IcalEventsFetch, RssFetch
-      ].freeze
-
-      def self.register_all(registry)
-        STEPS.each do |klass|
-          step = klass.new
-          step.name = klass.step_name
-          registry.register(step)
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/catalog.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # The single source of truth for step event names and their required
-    # kwargs. EventBus, RegistryStore, and the Loader all read these
-    # tables directly — the registries do not keep their own copies. Catalog
-    # references no other constant, so it has no load-order cycle, which is
-    # what removed the previous drift hazard (EventBus held a hard-coded
-    # `RPC_EVENTS` list that could fall out of sync with RpcRegistry's table).
-    module Catalog
-      # Pub-sub events: 0..N handlers, fire-and-forget, receive `ctx:`.
-      PUBSUB = {
-        entry_written: %i[ctx key envelope],
-        entry_deleted: %i[ctx key],
-        entry_fetched: %i[ctx key envelope change],
-        entry_renamed: %i[ctx key from_key to_key envelope],
-        entry_produced: %i[ctx key envelope sources],
-        produce_failed: %i[ctx keys error],
-        proposal_accepted: %i[ctx key target_key],
-        proposal_rejected: %i[ctx key target_key],
-        entry_published: %i[ctx key envelope source target],
-        store_loaded: %i[ctx],
-        session_opened: %i[ctx role cursor],
-        entry_fetch_started: %i[ctx key mode],
-        entry_fetch_failed: %i[ctx key error_class error_message],
-      }.freeze
-
-      # RPC events: single handler, return value matters, receive `caps:`.
-      RPC = {
-        resolve_handler: %i[caps config args],
-        transform_rows: %i[caps rows config],
-        validate: %i[caps],
-      }.freeze
-    end
-  end
-end

data/lib/textus/step/context.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # A narrow handle passed to user steps in place of the raw Store.
-    # All writes route back through the RoleScope so authorization, audit
-    # logging, and schema validation always fire.
-    class Context
-      attr_reader :role, :correlation_id
-
-      def self.for(container:, call:)
-        scope = Textus::Surfaces::RoleScope.new(
-          container: container,
-          role: call.role,
-          correlation_id: call.correlation_id,
-          dry_run: call.dry_run,
-        )
-        new(scope: scope)
-      end
-
-      def initialize(scope:)
-        @scope          = scope
-        @role           = scope.role
-        @correlation_id = scope.correlation_id
-      end
-
-      def backend
-        @scope
-      end
-
-      # read — a pure-observation surface: nothing here ingests. Since ADR 0089
-      # `get` itself is a pure read (the read-through that once forced this
-      # surface to opt out is gone, so the old re-entrancy/deadlock guard is no
-      # longer needed); `list`/`deps`/`freshness` are reads too. A hook observes
-      # current state and never triggers an I/O cascade.
-      def get(key)                = pure_reader.call(key)
-      def list(**)                = @scope.list(**)
-      def deps(key)               = @scope.deps(key)
-      def freshness(key)          = @scope.freshness(key)
-
-      # write (authorized + audited)
-      def put(key, **)          = @scope.put(key, **)
-      def delete(key, **)       = @scope.key_delete(key, **)
-
-      def audit(verb, key:, **)
-        @scope.container.audit_log.append(role: @role, verb: verb, key: key, **)
-      end
-
-      # fan-out
-      def publish_followup(event, **)
-        @scope.container.steps.publish(event, ctx: self, **)
-      end
-
-      def inspect
-        "#<Textus::Step::Context role=#{@role} correlation_id=#{@correlation_id}>"
-      end
-
-      private
-
-      def pure_reader
-        @pure_reader ||= lambda do |key|
-          Textus::Action::Get.new(key: key).call(
-            container: @scope.container,
-            call: Textus::Call.build(
-              role: @scope.role,
-              correlation_id: @scope.correlation_id,
-              dry_run: @scope.dry_run?,
-            ),
-          )
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/discovery.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Maps a discovered file path under .textus/steps to its (kind, name).
-    # kind = the directory segment directly under steps/; name = the basename
-    # without .rb (hyphens preserved). The single source of truth for valid
-    # kinds is the set of Base subclasses.
-    KINDS = %i[fetch transform validate observe].freeze
-
-    Discovery = Data.define(:kind, :name) do
-      def self.parse(path, base:)
-        rel = path.delete_prefix(base.to_s).delete_prefix("/")
-        parts = rel.split("/")
-        raise UsageError.new("step #{rel} must live under steps/<kind>/<name>.rb") unless parts.length == 2
-
-        kind = parts[0].to_sym
-        raise UsageError.new("unknown step kind '#{parts[0]}' (expected one of: #{KINDS.join(", ")})") unless KINDS.include?(kind)
-
-        new(kind: kind, name: File.basename(parts[1], ".rb").to_sym)
-      end
-    end
-  end
-end

data/lib/textus/step/error_log.rb

@@ -1,32 +0,0 @@
-module Textus
-  module Step
-    # Bounded in-memory ring buffer of recent hook failures (errored and
-    # timed_out). Each row carries the audit `seq` observed at the time of
-    # failure so pulse can filter "errors since cursor".
-    class ErrorLog
-      DEFAULT_CAPACITY = 256
-
-      def initialize(capacity: DEFAULT_CAPACITY)
-        @capacity = capacity
-        @rows = []
-        @mutex = Mutex.new
-      end
-
-      def record(seq:, event:, hook:, key:, error_class:, error_message:)
-        row = {
-          seq: seq, event: event, hook: hook, key: key,
-          error_class: error_class, error_message: error_message,
-          at: Time.now.utc.iso8601
-        }
-        @mutex.synchronize do
-          @rows << row
-          @rows.shift while @rows.size > @capacity
-        end
-      end
-
-      def since(seq)
-        @mutex.synchronize { @rows.select { |r| r[:seq] > seq }.dup }
-      end
-    end
-  end
-end

data/lib/textus/step/event_bus.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Textus
-  module Step
-    class EventBus
-      HOOK_TIMEOUT_SECONDS = 2
-
-      class HookTimeout < StandardError; end
-
-      def initialize(error_log: ErrorLog.new)
-        @pubsub = Hash.new { |h, k| h[k] = [] }
-        @error_handlers = []
-        @error_log = error_log
-      end
-
-      attr_reader :error_log
-
-      def on(event, name, keys: nil, &) = register(event, name, keys: keys, &)
-
-      def register(event, name, keys: nil, &blk)
-        event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if Catalog::RPC.key?(event_sym)
-
-        required = Catalog::PUBSUB[event_sym] or raise UsageError.new("unknown event: #{event}")
-        sig = Signature.new(blk)
-        missing = sig.missing(required)
-        if missing.any?
-          raise UsageError.new("#{event_sym} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
-        end
-
-        name = name.to_sym
-        raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
-
-        @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
-      end
-
-      def on_error(&block) = @error_handlers << block
-
-      def listeners(event, key:) = @pubsub[event.to_sym].select { |h| match?(h[:keys], key) }
-
-      def pubsub_handlers(event) = @pubsub[event.to_sym]
-
-      def pubsub_handlers_names = @pubsub.values.flatten.map { |h| h[:name] }
-
-      def publish(event, strict: false, **kwargs)
-        key = kwargs[:key] || "-"
-        fired = []
-        errored = []
-        timed_out = []
-        raised = nil
-
-        @pubsub[event.to_sym].each do |sub|
-          next unless match?(sub[:keys], key)
-
-          outcome, err = invoke(event, sub, key, kwargs)
-          case outcome
-          when :ok        then fired << sub[:name]
-          when :errored   then errored << sub[:name]
-          when :timed_out then timed_out << sub[:name]
-          end
-          raised ||= err if strict && err
-        end
-
-        raise raised if strict && raised
-
-        FireReport.new(fired: fired, errored: errored, timed_out: timed_out)
-      end
-
-      private
-
-      def invoke(event, sub, key, kwargs)
-        accepted = Signature.new(sub[:callable]).filter(kwargs)
-        begin
-          Timeout.timeout(HOOK_TIMEOUT_SECONDS) do
-            sub[:callable].call(**accepted)
-          end
-          [:ok, nil]
-        rescue Timeout::Error
-          err = HookTimeout.new("hook #{sub[:name]} exceeded #{HOOK_TIMEOUT_SECONDS}s on event #{event}")
-          notify_error(event, sub, key, kwargs, err)
-          [:timed_out, err]
-        rescue StandardError => e
-          notify_error(event, sub, key, kwargs, e)
-          [:errored, e]
-        end
-      end
-
-      def notify_error(event, sub, key, kwargs, error)
-        @error_log.record(
-          seq: kwargs[:_audit_seq] || -1,
-          event: event,
-          hook: sub[:name],
-          key: key,
-          error_class: error.class.name,
-          error_message: error.message,
-        )
-        @error_handlers.each do |handler|
-          handler.call(event: event, hook: sub[:name], key: key, kwargs: kwargs, error: error)
-        rescue StandardError => e
-          warn "[textus] error handler failed: #{e.class}: #{e.message}"
-        end
-      end
-
-      def match?(globs, key)
-        return true if globs.nil?
-
-        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
-      end
-    end
-  end
-end

data/lib/textus/step/fetch.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Acquires data from outside the store (the `fetch:` build input). Returns
-    # either { "content" => Hash } (structured) or { _meta:, body: } (rendered
-    # text). Replaces the :resolve_handler RPC. `caps:` is injected by the
-    # registry only if #call declares it.
-    class Fetch < Base
-      def self.required_kwargs = %i[config args]
-    end
-  end
-end

data/lib/textus/step/fire_report.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Outcome of a single Dispatcher#publish call.
-    #
-    # fired      — hook names that ran to completion
-    # errored    — hook names that raised
-    # timed_out  — hook names whose worker thread exceeded the deadline
-    #
-    # Callers that care about hook health (tests, strict embedders) can
-    # check #ok? or inspect #failures. The dispatcher itself never raises
-    # on a hook failure unless strict: true was passed to #publish.
-    FireReport = Data.define(:fired, :errored, :timed_out) do
-      def initialize(fired:, errored:, timed_out:)
-        super(fired: fired.dup.freeze, errored: errored.dup.freeze, timed_out: timed_out.dup.freeze)
-      end
-
-      def ok? = errored.empty? && timed_out.empty?
-      def failures = errored + timed_out
-    end
-  end
-end

data/lib/textus/step/loader.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Convention discovery: glob .textus/steps/<kind>/<name>.rb, load each file,
-    # validate the class it defines against the discovered kind, assign the
-    # discovered name, and register it. No global queue, no Textus.hook.
-    class Loader
-      BASE_FOR = {
-        fetch: Step::Fetch, transform: Step::Transform,
-        validate: Step::Validate, observe: Step::Observe
-      }.freeze
-
-      def initialize(registry:)
-        @registry = registry
-      end
-
-      def load_dir(dir)
-        return unless File.directory?(dir)
-
-        loaded_paths = Set.new
-        Dir.glob(File.join(dir, "**/*.rb")).sort.each do |path| # rubocop:disable Lint/RedundantDirGlobSort
-          real_path = File.realpath(path)
-          next if loaded_paths.include?(real_path)
-
-          loaded_paths << real_path
-          load_one(dir, path)
-        end
-      end
-
-      private
-
-      def load_one(dir, path)
-        disc = Discovery.parse(path, base: dir)
-        klass = capture_defined_class(path, disc)
-        validate!(disc, klass, path, dir)
-
-        step = klass.new
-        step.name = disc.name
-        @registry.register(step)
-      rescue StandardError, ScriptError => e
-        raise UsageError.new("failed loading step #{rel(dir, path)}: #{e.class}: #{e.message}") unless e.is_a?(UsageError)
-
-        raise
-      end
-
-      # Load the file and return the Step::Base subclass it newly defined.
-      def capture_defined_class(path, disc)
-        before = descendants
-        load(path)
-        defined = descendants - before
-        return defined.first if defined.length == 1
-        raise UsageError.new("step #{path} defined more than one Textus::Step subclass") if defined.length > 1
-
-        fallback = find_existing_class_for(disc)
-        return fallback if fallback
-
-        raise UsageError.new("step #{path} defined no Textus::Step subclass")
-      end
-
-      def find_existing_class_for(disc)
-        expected = inferred_class_name_for(disc)
-        candidates = descendants.select do |klass|
-          klass < BASE_FOR.fetch(disc.kind) && klass.name&.split("::")&.last == expected
-        end
-        return nil if candidates.empty?
-        return candidates.first if candidates.length == 1
-
-        namespaced = candidates.find { |klass| klass.name == "Textus::Step::#{expected}" }
-        namespaced || candidates.first
-      end
-
-      def inferred_class_name_for(disc)
-        stem = disc.name.to_s.split(/[-_]/).map(&:capitalize).join
-        suffix = { fetch: "Fetch", transform: "Transform", validate: "Validate", observe: "Observe" }.fetch(disc.kind)
-        "#{stem}#{suffix}"
-      end
-
-      def validate!(disc, klass, path, dir)
-        expected = BASE_FOR.fetch(disc.kind)
-        actual_kind = klass.respond_to?(:kind) ? safe_kind(klass) : nil
-        unless klass < expected
-          raise UsageError.new("#{rel(dir, path)} defines a #{actual_kind || "non-step"} step but lives under #{disc.kind}/")
-        end
-
-        sig = Step::Signature.new(klass.instance_method(:call))
-        missing = sig.missing(klass.required_kwargs)
-        return if missing.empty?
-
-        msg = "#{disc.kind} step '#{disc.name}' #call must accept kwargs: " \
-              "#{klass.required_kwargs.join(", ")} (missing: #{missing.join(", ")})"
-        raise UsageError.new(msg)
-      end
-
-      def safe_kind(klass)
-        klass.kind
-      rescue StandardError
-        nil
-      end
-
-      def descendants
-        ObjectSpace.each_object(Class).select { |c| c < Step::Base }
-      end
-
-      def rel(dir, path) = path.delete_prefix(dir.to_s).delete_prefix("/")
-    end
-  end
-end

data/lib/textus/step/observe.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Reacts to a lifecycle event (Catalog::PUBSUB). 0..N per event,
-    # fire-and-forget, no meaningful return, timeout-isolated by the EventBus.
-    # Declares its event with `on :event_name` and an optional key filter with
-    # `match "glob.**"`. Replaces user pub/sub subscribers.
-    class Observe < Base
-      def self.on(event = :__read__)
-        if event == :__read__
-          @event
-        else
-          @event = event.to_sym
-        end
-      end
-
-      def self.match(glob = :__read__)
-        if glob == :__read__
-          @match
-        else
-          @match = glob
-        end
-      end
-
-      class << self
-        attr_reader :event
-      end
-    end
-  end
-end