textus 0.8.0 → 0.9.2

data/lib/textus/doctor/check/legacy_intake_fields.rb

@@ -0,0 +1,57 @@
+require "yaml"
+
+module Textus
+  module Doctor
+    class Check
+      # Scans the raw manifest YAML for entry-level intake.ttl /
+      # intake.on_stale / intake.sync_budget_ms keys. Manifest parsing
+      # already raises on these in 0.9.2 — this check exists for the case
+      # where doctor is run against a problem manifest separately (e.g. CI
+      # lint or an exploration session that loads the YAML directly).
+      class LegacyIntakeFields < Check
+        LEGACY_KEYS = %w[ttl on_stale sync_budget_ms].freeze
+
+        def call
+          out = []
+          path = File.join(store.root, "manifest.yaml")
+          return out unless File.exist?(path)
+
+          raw = safe_load(path)
+          return out unless raw.is_a?(Hash)
+
+          Array(raw["entries"]).each do |entry|
+            next unless entry.is_a?(Hash)
+
+            intake = entry["intake"]
+            next unless intake.is_a?(Hash)
+
+            offending = LEGACY_KEYS.select { |k| intake.key?(k) }
+            next if offending.empty?
+
+            out << issue_for(entry["key"], offending)
+          end
+          out
+        end
+
+        private
+
+        def safe_load(path)
+          YAML.load_file(path)
+        rescue StandardError
+          nil
+        end
+
+        def issue_for(key, fields)
+          {
+            "code" => "manifest.legacy_intake_fields",
+            "level" => "error",
+            "subject" => key.to_s,
+            "message" => "entry '#{key}' carries legacy intake.#{fields.join(", intake.")} " \
+                         "(removed in 0.9.2 — freshness lives in top-level policies:)",
+            "fix" => "hand-edit these into a top-level policies: block (see CHANGELOG migration recipe)",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/policy_ambiguity.rb

@@ -0,0 +1,49 @@
+module Textus
+  module Doctor
+    class Check
+      # Flags entries whose key is matched by two or more policy blocks of the
+      # SAME specificity in the same slot (refresh / handler_allowlist /
+      # promote). Ties are non-deterministic in the parser's pick step, so
+      # they're a configuration smell — surface them.
+      class PolicyAmbiguity < Check
+        SLOTS = %i[refresh handler_allowlist promote].freeze
+
+        def call
+          out = []
+          policies = store.manifest.policies
+          store.manifest.entries.each do |mentry|
+            matches = policies.explain(mentry.key)
+            next if matches.length < 2
+
+            SLOTS.each { |slot| out.concat(ambiguities_for(mentry, slot, matches)) }
+          end
+          out
+        end
+
+        private
+
+        def ambiguities_for(mentry, slot, matches)
+          carriers = matches.select { |b| b.public_send(slot) }
+          return [] if carriers.length < 2
+
+          by_specificity = carriers.group_by { |b| Textus::Domain::Policy::Matcher.specificity(b.match) }
+          tied = by_specificity.values.select { |group| group.length > 1 }
+          tied.map { |group| issue_for(mentry, slot, group) }
+        end
+
+        def issue_for(mentry, slot, group)
+          globs = group.map(&:match).sort
+          {
+            "code" => "policy.ambiguity",
+            "level" => "warning",
+            "subject" => mentry.key,
+            "message" => "entry '#{mentry.key}' matches #{group.length} policy blocks at the same " \
+                         "specificity for #{slot}: #{globs.join(", ")}",
+            "fix" => "narrow one of the conflicting match: globs in .textus/manifest.yaml so a single " \
+                     "block wins for this key",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -13,11 +13,15 @@ module Textus
       Check::Schemas,
       Check::Templates,
       Check::Hooks,
+      Check::IntakeRegistration,
       Check::IllegalKeys,
       Check::Sentinels,
       Check::AuditLog,
       Check::UnownedSchemaFields,
       Check::SchemaViolations,
+      Check::PolicyAmbiguity,
+      Check::HandlerAllowlist,
+      Check::LegacyIntakeFields,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze
@@ -67,7 +71,7 @@ module Textus
         rescue StandardError => e
           out << fail_issue(name, code: "doctor_check.failed",
                                   message: "#{e.class}: #{e.message}",
-                                  fix: "fix the doctor_check block in .textus/extensions/")
+                                  fix: "fix the :check hook in .textus/hooks/")
         end
       end
       out

data/lib/textus/domain/action.rb

@@ -0,0 +1,9 @@
+module Textus
+  module Domain
+    module Action
+      Return       = Data.define
+      RefreshSync  = Data.define
+      RefreshTimed = Data.define(:budget_ms)
+    end
+  end
+end

data/lib/textus/domain/freshness/evaluator.rb

@@ -0,0 +1,30 @@
+require "time"
+
+module Textus
+  module Domain
+    module Freshness
+      module Evaluator
+        module_function
+
+        def call(policy, envelope, now:)
+          return Verdict.fresh if policy.ttl_seconds.nil?
+
+          last_str = envelope.dig("_meta", "last_refreshed_at")
+          return Verdict.stale("never refreshed") if last_str.nil?
+
+          last = begin
+            Time.parse(last_str.to_s)
+          rescue ArgumentError, TypeError
+            nil
+          end
+          return Verdict.stale("unparseable last_refreshed_at: #{last_str.inspect}") if last.nil?
+
+          age = now - last
+          return Verdict.fresh if age <= policy.ttl_seconds
+
+          Verdict.stale("ttl exceeded (age=#{age.to_i}s, ttl=#{policy.ttl_seconds}s)")
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/freshness/policy.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Domain
+    module Freshness
+      Policy = Data.define(:ttl_seconds, :on_stale, :sync_budget_ms) do
+        def decide(verdict)
+          return Action::Return.new if verdict.fresh?
+
+          case on_stale
+          when :warn       then Action::Return.new
+          when :sync       then Action::RefreshSync.new
+          when :timed_sync then Action::RefreshTimed.new(budget_ms: sync_budget_ms)
+          else                  Action::Return.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/freshness/verdict.rb

@@ -0,0 +1,12 @@
+module Textus
+  module Domain
+    module Freshness
+      Verdict = Data.define(:fresh, :reason) do
+        def self.fresh         = new(fresh: true, reason: nil)
+        def self.stale(reason) = new(fresh: false, reason: reason)
+        def fresh? = fresh
+        def stale? = !fresh
+      end
+    end
+  end
+end

data/lib/textus/domain/outcome.rb

@@ -0,0 +1,10 @@
+module Textus
+  module Domain
+    module Outcome
+      Skipped   = Data.define
+      Refreshed = Data.define(:envelope)
+      Detached  = Data.define
+      Failed    = Data.define(:error)
+    end
+  end
+end

data/lib/textus/domain/permission.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Domain
+    Permission = Data.define(:zone, :writable_by, :readable_by) do
+      def allows_write?(role)
+        writable_by.include?(role.to_s)
+      end
+
+      def allows_read?(role)
+        return true if readable_by == :all
+
+        readable_by.include?(role.to_s)
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/handler_allowlist.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Domain
+    module Policy
+      class HandlerAllowlist
+        attr_reader :handlers
+
+        def initialize(handlers:)
+          @handlers = Array(handlers).map(&:to_s).freeze
+        end
+
+        def allows?(handler)
+          @handlers.include?(handler.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/matcher.rb

@@ -0,0 +1,51 @@
+module Textus
+  module Domain
+    module Policy
+      module Matcher
+        module_function
+
+        def matches?(glob, key)
+          glob_segs = glob.split(".")
+          key_segs  = key.split(".")
+          consume(glob_segs, key_segs)
+        end
+
+        def specificity(glob)
+          glob.split(".").reduce(0) do |s, seg|
+            s + case seg
+                when "**" then 0
+                when "*"  then 1
+                else 10
+                end
+          end
+        end
+
+        def pick_most_specific(globs, key:)
+          matching = globs.select { |g| matches?(g, key) }
+          return nil if matching.empty?
+
+          matching.max_by { |g| [specificity(g), -g.length, g] }
+        end
+
+        def self.consume(glob_segs, key_segs)
+          return key_segs.empty? if glob_segs.empty?
+
+          head = glob_segs.first
+          rest = glob_segs[1..]
+
+          if head == "**"
+            return true if rest.empty?
+
+            (0..key_segs.length).any? { |i| consume(rest, key_segs[i..]) }
+          elsif key_segs.empty?
+            false
+          elsif head == "*" || head == key_segs.first
+            consume(rest, key_segs[1..])
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/promote.rb

@@ -0,0 +1,24 @@
+module Textus
+  module Domain
+    module Policy
+      class Promote
+        KNOWN = %i[schema_valid human_accept].freeze
+        attr_reader :requires
+
+        def initialize(requires:)
+          syms = Array(requires).map { |r| r.to_s.to_sym }
+          unknown = syms - KNOWN
+          unless unknown.empty?
+            raise Textus::UsageError.new("unknown promote requirement: #{unknown.first.inspect} (known: #{KNOWN.join(", ")})")
+          end
+
+          @requires = syms
+        end
+
+        def demands?(req)
+          @requires.include?(req)
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/refresh.rb

@@ -0,0 +1,48 @@
+module Textus
+  module Domain
+    module Policy
+      class Refresh
+        attr_reader :ttl, :on_stale, :sync_budget_ms
+
+        def initialize(ttl:, on_stale:, sync_budget_ms:)
+          on_stale_sym = on_stale.is_a?(Symbol) ? on_stale : on_stale.to_s.to_sym
+          unless ALLOWED_ON_STALE.include?(on_stale_sym)
+            raise Textus::UsageError.new(
+              "on_stale must be one of #{ALLOWED_ON_STALE.join(", ")} (got #{on_stale.inspect})",
+            )
+          end
+
+          @ttl            = ttl
+          @on_stale       = on_stale_sym
+          @sync_budget_ms = sync_budget_ms
+        end
+
+        def ttl_seconds
+          return nil if @ttl.nil?
+
+          str = @ttl.to_s.strip
+          return str.to_i if str.match?(/\A\d+\z/)
+
+          m = str.match(/\A(\d+)\s*([smhd])\z/)
+          return nil unless m
+
+          n = m[1].to_i
+          case m[2]
+          when "s" then n
+          when "m" then n * 60
+          when "h" then n * 3600
+          when "d" then n * 86_400
+          end
+        end
+
+        def to_freshness_policy
+          Textus::Domain::Freshness::Policy.new(
+            ttl_seconds: ttl_seconds,
+            on_stale: @on_stale,
+            sync_budget_ms: @sync_budget_ms,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy.rb

@@ -0,0 +1,7 @@
+module Textus
+  module Domain
+    module Policy
+      ALLOWED_ON_STALE = %i[warn sync timed_sync].freeze
+    end
+  end
+end

data/lib/textus/hooks/builtin.rb

@@ -8,21 +8,21 @@ module Textus
     module Builtin
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def self.register_all
-        Textus.hook(:fetch, :json) do |store:, config:, args:|
+        Textus.hook(:intake, :json) do |store:, config:, args:|
           _ = store
           _ = args
           data = JSON.parse(config["bytes"].to_s)
           { _meta: {}, body: YAML.dump(data) }
         end
 
-        Textus.hook(:fetch, :csv) do |store:, config:, args:|
+        Textus.hook(:intake, :csv) do |store:, config:, args:|
           _ = store
           _ = args
           rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
           { _meta: {}, body: YAML.dump(rows) }
         end
 
-        Textus.hook(:fetch, :"markdown-links") do |store:, config:, args:|
+        Textus.hook(:intake, :"markdown-links") do |store:, config:, args:|
           _ = store
           _ = args
           links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
@@ -31,7 +31,7 @@ module Textus
           { _meta: {}, body: YAML.dump(links) }
         end
 
-        Textus.hook(:fetch, :"ical-events") do |store:, config:, args:|
+        Textus.hook(:intake, :"ical-events") do |store:, config:, args:|
           _ = store
           _ = args
           events = []
@@ -50,7 +50,7 @@ module Textus
           { _meta: {}, body: YAML.dump(events) }
         end
 
-        Textus.hook(:fetch, :rss) do |store:, config:, args:|
+        Textus.hook(:intake, :rss) do |store:, config:, args:|
           _ = store
           _ = args
           doc = REXML::Document.new(config["bytes"].to_s)

data/lib/textus/hooks/dispatcher.rb

@@ -28,7 +28,8 @@ module Textus
       private
 
       def invoke(event, sub, key, kwargs)
-        Timeout.timeout(HOOK_TIMEOUT_SECONDS) { sub[:callable].call(**kwargs) }
+        accepted = filter_kwargs(sub[:callable], kwargs)
+        Timeout.timeout(HOOK_TIMEOUT_SECONDS) { sub[:callable].call(**accepted) }
       rescue StandardError => e
         extras = { "event" => event.to_s, "hook" => sub[:name].to_s, "error" => "#{e.class}: #{e.message}" }
         extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
@@ -39,6 +40,19 @@ module Textus
         )
       end
 
+      # Passes only the kwargs a hook block declares. Lets us extend event
+      # payloads (e.g., correlation_id) without breaking hooks written against
+      # the old signature.
+      def filter_kwargs(callable, kwargs)
+        params = callable.parameters
+        return kwargs if params.any? { |type, _| type == :keyrest }
+
+        accepted = params.each_with_object([]) do |(type, name), acc|
+          acc << name if %i[key keyreq].include?(type)
+        end
+        kwargs.slice(*accepted)
+      end
+
       def match?(globs, key)
         return true if globs.nil?
 

data/lib/textus/hooks/dsl.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Hooks
+    module Dsl
+      EVENTS = %i[
+        intake reduce check
+        put deleted refreshed built published accepted
+        mv reject loaded
+        refresh_began refresh_failed refresh_detached
+      ].freeze
+
+      EVENTS.each do |event|
+        define_method(event) do |name, **opts, &blk|
+          Loader.current_registry.register(event, name, **opts, &blk)
+        end
+      end
+    end
+  end
+end

data/lib/textus/hooks/registry.rb

@@ -3,16 +3,23 @@ module Textus
     class Registry
       EVENTS = {
         # RPC: exactly 1 handler per name; return value flows into store; failure aborts.
-        fetch: { mode: :rpc, args: %i[store config args] },
+        intake: { mode: :rpc, args: %i[store config args] },
         reduce: { mode: :rpc, args: %i[store rows config] },
         check: { mode: :rpc, args: %i[store] },
 
         # Pub-sub: 0..N handlers per event; return discarded; failure logged to audit.
         put: { mode: :pubsub, args: %i[store key envelope] },
-        delete: { mode: :pubsub, args: %i[store key] },
-        refresh: { mode: :pubsub, args: %i[store key envelope change] },
-        build: { mode: :pubsub, args: %i[store key envelope sources] },
-        accept: { mode: :pubsub, args: %i[store key target_key] },
+        deleted: { mode: :pubsub, args: %i[store key] },
+        refreshed: { mode: :pubsub, args: %i[store key envelope change] },
+        built: { mode: :pubsub, args: %i[store key envelope sources] },
+        accepted: { mode: :pubsub, args: %i[store key target_key] },
+        published: { mode: :pubsub, args: %i[store key envelope source target] },
+        mv: { mode: :pubsub, args: %i[store key from_key to_key envelope] },
+        reject: { mode: :pubsub, args: %i[store key target_key] },
+        loaded: { mode: :pubsub, args: %i[store] },
+        refresh_began: { mode: :pubsub, args: %i[store key mode] },
+        refresh_failed: { mode: :pubsub, args: %i[store key error_class error_message] },
+        refresh_detached: { mode: :pubsub, args: %i[store key started_at budget_ms] },
       }.freeze
 
       def initialize(dispatcher: nil)

data/lib/textus/infra/clock.rb

@@ -0,0 +1,9 @@
+module Textus
+  module Infra
+    module Clock
+      module_function
+
+      def now = Time.now
+    end
+  end
+end

data/lib/textus/infra/event_bus.rb

@@ -0,0 +1,27 @@
+module Textus
+  module Infra
+    class EventBus
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      def publish(event, **payload)
+        @registry.pubsub_handlers(event).each do |entry|
+          next unless entry[:keys].nil? || matches?(entry[:keys], payload[:key])
+
+          entry[:callable].call(**payload)
+        rescue StandardError => e
+          warn "[textus] pub-sub handler #{entry[:name].inspect} for #{event.inspect} failed: #{e.class}: #{e.message}"
+        end
+      end
+
+      private
+
+      def matches?(globs, key)
+        return true if key.nil?
+
+        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
+      end
+    end
+  end
+end

data/lib/textus/infra/publisher.rb

@@ -0,0 +1,73 @@
+require "json"
+require "digest"
+require "fileutils"
+
+module Textus
+  module Infra
+    # Publishes built artifacts from the store to repo-relative consumer paths.
+    # Publish = copy + sentinel. The in-store file is already the consumer-shaped
+    # artifact; no parsing or stripping. Sentinels live under
+    # `<store_root>/sentinels/` and mirror the target's repo-relative layout so
+    # consumer directories aren't polluted with `.textus-managed.json` siblings.
+    module Publisher
+      SENTINEL_SUFFIX = ".textus-managed.json".freeze
+      SENTINEL_DIR    = "sentinels".freeze
+
+      def self.publish(source:, target:, store_root:)
+        FileUtils.mkdir_p(File.dirname(target))
+        refuse_if_unmanaged(target, store_root)
+        File.delete(target) if File.symlink?(target)
+        FileUtils.cp(source, target)
+        write_sentinel(target, store_root: store_root, source: source)
+        cleanup_legacy_sentinel(target)
+      end
+
+      def self.refuse_if_unmanaged(target, store_root)
+        return unless File.exist?(target) || File.symlink?(target)
+        return if managed?(target, store_root)
+
+        raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
+      end
+
+      def self.managed?(target, store_root)
+        File.exist?(sentinel_path(target, store_root)) || File.exist?(legacy_sentinel_path(target))
+      end
+
+      def self.write_sentinel(target, store_root:, source:)
+        path = sentinel_path(target, store_root)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.generate(
+                           "source" => source,
+                           "target" => target,
+                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
+                           "mode" => "copy",
+                         ))
+      end
+
+      # Sentinel layout: <store_root>/sentinels/<target_rel_to_repo>.textus-managed.json
+      # The full target extension is preserved so a marketplace.json and
+      # marketplace.yaml don't collide.
+      def self.sentinel_path(target, store_root)
+        repo_root = File.dirname(store_root)
+        rel = relative_to(target, repo_root) || File.basename(target)
+        File.join(store_root, SENTINEL_DIR, rel + SENTINEL_SUFFIX)
+      end
+
+      def self.legacy_sentinel_path(target)
+        target + SENTINEL_SUFFIX
+      end
+
+      def self.cleanup_legacy_sentinel(target)
+        FileUtils.rm_f(legacy_sentinel_path(target))
+      end
+
+      def self.relative_to(path, base)
+        path = File.expand_path(path)
+        base = File.expand_path(base)
+        return nil unless path.start_with?(base + File::SEPARATOR)
+
+        path[(base.length + 1)..]
+      end
+    end
+  end
+end

data/lib/textus/infra/refresh/detached.rb

@@ -0,0 +1,38 @@
+module Textus
+  module Infra
+    module Refresh
+      module Detached
+        module_function
+
+        def supported?
+          Process.respond_to?(:fork)
+        end
+
+        def spawn(store_root:, key:)
+          return nil unless supported?
+
+          pid = Process.fork do
+            $stdin.close
+            $stdout.reopen(File::NULL, "w")
+            $stderr.reopen(File::NULL, "w")
+
+            lock = Textus::Infra::Refresh::Lock.new(root: store_root, key: key)
+            exit(0) unless lock.try_acquire
+
+            begin
+              store = Textus::Store.new(store_root)
+              Textus::Refresh.call(store, key, as: "script")
+            rescue StandardError
+              # Already logged via :refresh_failed; exit cleanly.
+            ensure
+              lock.release
+              exit(0)
+            end
+          end
+          Process.detach(pid)
+          pid
+        end
+      end
+    end
+  end
+end