textus 0.51.0 → 0.53.0

data/lib/textus/action/rule_explain.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class RuleExplain < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_explain
+      summary "Effective rules for a key. Lean {lifecycle, guard} by default; detail: true adds matched blocks + guard predicates."
+      surfaces :cli, :mcp
+      cli "rule explain"
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key whose effective rules you want (lifecycle ttl/action, write guard, ...)"
+      arg :detail, :boolean,
+          description: "defaults false: lean {lifecycle, guard}. detail: true adds matched blocks + guard predicates per transition."
+      view(:cli) { |r| { "verb" => "rule_explain" }.merge(r.transform_keys(&:to_s)) }
+
+      BURN = :sync
+
+      def initialize(key:, detail: nil)
+        super()
+        @key = key
+        @detail = detail
+      end
+
+      def call(container:, **)
+        @manifest = container.manifest
+        @detail ? explain(@key) : effective(@key)
+      end
+
+      REGISTRY = Textus::Manifest::Schema::FIELD_REGISTRY
+      LEAN_FIELDS = REGISTRY.select { |_, m| m[:in_rule_explain].include?(:lean) }.keys.freeze
+      DETAIL_FIELDS = REGISTRY.select { |_, m| m[:in_rule_explain].include?(:detail) }.keys.freeze
+      EFFECTIVE_FIELDS = DETAIL_FIELDS.select { |f| REGISTRY[f][:policy_class] }.freeze
+
+      private
+
+      def effective(key)
+        set = @manifest.rules.for(key)
+        LEAN_FIELDS.each_with_object({}) do |field, out|
+          value = set.public_send(field)
+          out[field.to_s] = lean_value(field, value) unless value.nil?
+        end
+      end
+
+      def lean_value(field, value)
+        case field
+        when :retention
+          retention_hash(value, string_keys: true)
+        when :react
+          value.to_h
+        else
+          value
+        end
+      end
+
+      def explain(key)
+        matching = @manifest.rules.explain(key)
+        winners = @manifest.rules.for(key)
+        {
+          key: key,
+          matched_blocks: matching.map do |block|
+            { match: block.match }.merge(DETAIL_FIELDS.to_h { |f| [f, !block.public_send(f).nil?] })
+          end,
+          effective: EFFECTIVE_FIELDS.to_h { |f| [f, effective_value(f, winners.public_send(f))] },
+          guards: Textus::Gate::Auth::FLOOR.keys.to_h do |action|
+            floor = Textus::Gate::Auth::FLOOR.fetch(action, [])
+            rule = Array(@manifest.rules.for(key).guard&.dig(action.to_s))
+            [action, { floor: floor, rule: rule }]
+          end,
+        }
+      end
+
+      def effective_value(field, value)
+        return nil if value.nil?
+
+        case field
+        when :retention
+          retention_hash(value, string_keys: false)
+        when :react
+          value.to_h
+        when :handler_permit
+          value.handlers
+        else
+          value
+        end
+      end
+
+      def retention_hash(retention, string_keys:)
+        h = { ttl_seconds: retention.ttl_seconds, action: retention.action }
+        string_keys ? h.transform_keys(&:to_s) : h
+      end
+    end
+  end
+end

data/lib/textus/action/rule_lint.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Textus
+  module Action
+    class RuleLint < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_lint
+      summary "Diff candidate manifest YAML's rules against the live manifest. No writes."
+      surfaces :cli, :mcp
+      cli "rule lint"
+      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
+                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
+      view { |v, _i| v.to_h }
+
+      BURN = :sync
+
+      def initialize(candidate_yaml:)
+        super()
+        @candidate_yaml = candidate_yaml
+      end
+
+      def call(container:, **)
+        root = container.root
+        live_rules = current_rules(root)
+        candidate_rules = parse_candidate(@candidate_yaml)
+
+        live_by_match = live_rules.to_h { |rule| [rule["match"], rule] }
+        candidate_by_match = candidate_rules.to_h { |rule| [rule["match"], rule] }
+
+        steps = (candidate_by_match.keys - live_by_match.keys).map do |match|
+          { "op" => "add_rule", "match" => match, "rule" => candidate_by_match[match] }
+        end
+        (live_by_match.keys - candidate_by_match.keys).each do |match|
+          steps << { "op" => "remove_rule", "match" => match }
+        end
+        (live_by_match.keys & candidate_by_match.keys).each do |match|
+          next if live_by_match[match] == candidate_by_match[match]
+
+          steps << {
+            "op" => "change_rule",
+            "match" => match,
+            "from" => live_by_match[match],
+            "to" => candidate_by_match[match],
+          }
+        end
+
+        Textus::Background::Plan.new(steps: steps, warnings: [])
+      end
+
+      private
+
+      def current_rules(root)
+        raw = YAML.safe_load_file(File.join(root, "manifest.yaml"), permitted_classes: [Symbol], aliases: false)
+        Array(raw["rules"])
+      end
+
+      def parse_candidate(yaml_text)
+        raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
+        raise UsageError.new("candidate is not a YAML mapping") unless raw.is_a?(Hash)
+
+        Array(raw["rules"])
+      rescue Psych::Exception => e
+        raise UsageError.new("candidate YAML parse error: #{e.message}")
+      end
+    end
+  end
+end

data/lib/textus/action/rule_list.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class RuleList < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_list
+      summary "List every rule block in the manifest."
+      surfaces :cli
+      cli "rule list"
+      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
+
+      BURN = :sync
+
+      def call(container:, **)
+        manifest = container.manifest
+        manifest.rules.blocks.map do |block|
+          row = { "match" => block.match }
+          self.class::LIST_FIELDS.each do |field|
+            value = block.public_send(field)
+            row[field.to_s] = serialize(field, value) unless value.nil?
+          end
+          row
+        end
+      end
+
+      LIST_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_rule_list] }.keys.freeze
+
+      private
+
+      def serialize(field, value)
+        case field
+        when :retention
+          { "ttl_seconds" => value.ttl_seconds, "action" => value.action.to_s }
+        when :react
+          value.to_h
+        when :handler_permit
+          value.handlers
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/schema_envelope.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class SchemaEnvelope < Base
+      extend Textus::Contract::DSL
+
+      verb :schema_show
+      summary "Return the schema (field shape) for an entry's family, by key."
+      surfaces :cli, :mcp
+      cli "schema show"
+      arg :key, String, required: true, positional: true,
+                        description: "any key in the family whose schema you want; returns required/optional fields and their types"
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        manifest = container.manifest
+        schemas = container.schemas
+        mentry = manifest.resolver.resolve(@key).entry
+        schema = schemas.fetch_or_nil(mentry.schema)
+        { "protocol" => PROTOCOL, "key" => @key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
+      end
+    end
+  end
+end

data/lib/textus/action/uid.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Uid < Base
+      extend Textus::Contract::DSL
+
+      verb :uid
+      summary "Return the stable UID of an entry without reading its body."
+      surfaces :cli
+      cli "key uid"
+      arg :key, String, required: true, positional: true, description: "entry key"
+      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call:)
+        Textus::Action::Get.new(key: @key).call(container: container, call: call).uid
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/where.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Where < Base
+      extend Textus::Contract::DSL
+
+      verb :where
+      summary "Resolve a key to its zone, owner, and path without reading the body."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        manifest = container.manifest
+        res = manifest.resolver.resolve(@key)
+        mentry = res.entry
+        path = res.path
+        { "protocol" => PROTOCOL, "key" => @key, "lane" => mentry.lane, "owner" => mentry.owner, "path" => path }
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/write_verb.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class WriteVerb < Base
+      private
+
+      def auth(container)
+        Textus::Gate::Auth.new(container)
+      end
+
+      def writer(container, call)
+        Textus::Envelope::IO::Writer.from(container: container, call: call)
+      end
+
+      def reader(container)
+        Textus::Envelope::IO::Reader.from(container: container)
+      end
+
+      def run_with_cascade(target_key, container:, call:)
+        result = yield
+        cascade_to_rdeps(target_key, container, call) if target_key
+        result
+      end
+
+      def cascade_to_rdeps(key, container, call)
+        return if derived_write?(key, container)
+
+        rdeps = Textus::Action::Rdeps.new(key: key).call(container: container, call: call).fetch("rdeps", [])
+        producible = rdeps.select { |dep_key| producible?(dep_key, container) }
+        return if producible.empty?
+
+        producible.each do |dep_key|
+          Textus::Background::Job::Materialize.new(key: dep_key).call(container:, call:)
+        end
+        container.steps.publish(
+          :entry_written,
+          ctx: Textus::Step::Context.for(container: container, call: call),
+          key: key,
+          envelope: nil,
+        )
+      end
+
+      def derived_write?(key, container)
+        container.manifest.resolver.resolve(key).entry.derived?
+      rescue Textus::Error
+        false
+      end
+
+      def producible?(key, container)
+        entry = container.manifest.resolver.resolve(key).entry
+        entry.derived? || !entry.publish_tree.nil?
+      rescue Textus::Error
+        false
+      end
+    end
+  end
+end

data/lib/textus/background/job/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Base
+        def self.inherited(subclass)
+          super
+          return unless subclass.name
+
+          TracePoint.new(:end) do |tp|
+            if tp.self == subclass
+              Textus::Background::Job.register(subclass)
+              tp.disable
+            end
+          end.enable
+        end
+
+        def call(**)
+          raise NotImplementedError.new("#{self.class}#call")
+        end
+
+        def args = {}
+      end
+    end
+  end
+end

data/lib/textus/background/job/materialize.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Materialize < Base
+        TYPE = "materialize"
+
+        def initialize(key:)
+          super()
+          @key = key
+        end
+
+        def args = { key: @key }
+
+        def call(container:, call:)
+          result = Textus::Pipeline::Engine.converge(container: container, call: call, keys: [@key])
+          return unless result.is_a?(Hash)
+
+          Array(result[:failed]).each do |failure|
+            container.steps.publish(
+              :produce_failed,
+              ctx: Textus::Step::Context.for(container: container, call: call),
+              keys: [failure["key"]], error: failure["error"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/job/refresh.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Refresh < Base
+        TYPE = "refresh"
+
+        def initialize(key:)
+          super()
+          @key = key
+        end
+
+        def args = { key: @key }
+
+        def call(container:, call:)
+          Textus::Pipeline::Engine.converge(container: container, call: call, keys: [@key])
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/job/sweep.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Sweep < Base
+        REQUIRED_ROLE = Textus::Role::AUTOMATION
+        TYPE = "sweep"
+
+        def initialize(scope: nil, key: nil)
+          super()
+          @scope = scope || {}
+          @key   = key
+        end
+
+        def args = { scope: @scope, key: @key }.compact
+
+        def call(container:, call:)
+          prefix = @key || (@scope.is_a?(Hash) ? @scope["prefix"] : nil)
+          lane   = @scope.is_a?(Hash) ? @scope["lane"] : nil
+          rows = Textus::Core::Retention::Sweep.new(
+            manifest: container.manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+            clock: Textus::Ports::Clock.new,
+          ).call(prefix: prefix, lane: lane)
+          Textus::Background::Retention::Apply.new(container: container, call: call).call(rows)
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      @registry = {}
+
+      def self.registry = @registry
+
+      def self.register(klass)
+        @registry[klass::TYPE] = klass if klass.const_defined?(:TYPE, false)
+      end
+
+      def self.fetch(type)
+        @registry.fetch(type) { raise Textus::UsageError.new("unknown job type: #{type}") }
+      end
+    end
+  end
+end

data/lib/textus/background/plan.rb

@@ -0,0 +1,9 @@
+module Textus
+  module Background
+    Plan = Data.define(:steps, :warnings) do
+      def to_h
+        { "steps" => steps, "warnings" => warnings }
+      end
+    end
+  end
+end

data/lib/textus/background/planner/plan.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Planner
+      class Plan
+        ACTIONS_BY_TRIGGER = {
+          "convergence" => %w[materialize refresh sweep],
+          "entry.written" => %w[materialize],
+          "entry.deleted" => %w[materialize],
+          "entry.moved" => %w[materialize],
+          "proposal.accepted" => %w[materialize],
+          "proposal.rejected" => %w[materialize],
+        }.freeze
+
+        SCOPE_RESOLVERS = {
+          "materialize" => :producible_keys,
+          "refresh" => :stale_intake_keys,
+          "sweep" => :lane_keys,
+        }.freeze
+
+        def self.seed(container:, queue:, role:)
+          jobs = new(container: container).plan(
+            trigger: { "type" => "convergence" },
+            role: role,
+          )
+          jobs.each { |j| queue.enqueue(j) }
+        end
+
+        def initialize(container:)
+          @container = container
+          @manifest  = container.manifest
+        end
+
+        def plan(trigger:, role:)
+          type = trigger["type"] || trigger[:type]
+          trigger["target"] || trigger[:target]
+          return [] if type.nil?
+
+          blocks_with_react = @manifest.rules.blocks.select(&:react)
+          if blocks_with_react.any?
+            plan_from_rules(blocks_with_react, type, role)
+          else
+            plan_from_defaults(type, role)
+          end
+        end
+
+        private
+
+        def plan_from_rules(blocks, type, role)
+          jobs = []
+          blocks
+            .select { |b| matches_trigger?(b.react, type) }
+            .each do |block|
+              do_action = block.react.raw["do"]
+              Array(do_action).each do |action|
+                if action == "sweep"
+                  jobs << Textus::Ports::Queue::Job.new(
+                    type: "sweep", args: { "scope" => {} }, enqueued_by: role,
+                  )
+                else
+                  resolver = SCOPE_RESOLVERS.fetch(action, :producible_keys)
+                  keys = send(resolver, nil)
+                  keys.each { |key| jobs << job(action, key, role) }
+                end
+              end
+            end
+          jobs
+        end
+
+        def plan_from_defaults(type, role)
+          actions = ACTIONS_BY_TRIGGER.fetch(type, [])
+          jobs = []
+          producible_keys(nil).each { |k| jobs << job("materialize", k, role) } if actions.include?("materialize")
+          stale_intake_keys(nil).each { |k| jobs << job("refresh", k, role) } if actions.include?("refresh")
+          if actions.include?("sweep")
+            jobs << Textus::Ports::Queue::Job.new(
+              type: "sweep", args: { "scope" => {} }, enqueued_by: role,
+            )
+          end
+          jobs
+        end
+
+        def matches_trigger?(react, type)
+          on = react.raw["on"]
+          Array(on).include?(type)
+        end
+
+        def job(type, key, enqueued_by)
+          Textus::Ports::Queue::Job.new(type: type, args: { "key" => key }, enqueued_by: enqueued_by)
+        end
+
+        def producible_keys(_target)
+          @manifest.data.entries
+                   .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
+                   .map(&:key)
+        end
+
+        def stale_intake_keys(_target)
+          Textus::Core::Freshness::Evaluator.new(
+            manifest: @manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+            clock: Textus::Ports::Clock.new,
+          ).stale_intake_keys(prefix: nil, lane: nil)
+        end
+
+        def lane_keys(_target)
+          @manifest.data.entries.map(&:key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/retention/apply.rb

@@ -0,0 +1,50 @@
+require "fileutils"
+
+module Textus
+  module Background
+    module Retention
+      class Apply
+        def initialize(container:, call:)
+          @container = container
+          @call = call
+        end
+
+        def call(rows)
+          out = { dropped: [], archived: [], failed: [] }
+          rows.each do |row|
+            key = row["key"]
+            begin
+              case row["action"]
+              when "drop"
+                delete(key)
+                out[:dropped] << key
+              when "archive"
+                archive_leaf(row)
+                delete(key)
+                out[:archived] << key
+              end
+            rescue Textus::Error => e
+              out[:failed] << { "key" => key, "error" => e.message }
+            end
+          end
+          out
+        end
+
+        private
+
+        def archive_leaf(row)
+          src  = row["path"]
+          root = @container.root.to_s
+          rel  = src.delete_prefix("#{root}/")
+          dest = File.join(root, "archive", rel)
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(src, dest)
+        end
+
+        def delete(key)
+          Textus::Action::KeyDelete.new(key: key).call(container: @container, call: @call)
+        end
+      end
+    end
+  end
+end