textus 0.20.2 → 0.26.0

data/lib/textus/application/refresh/worker.rb

@@ -1,116 +0,0 @@
-require "timeout"
-
-module Textus
-  module Application
-    module Refresh
-      class Worker
-        FETCH_TIMEOUT_SECONDS = 30
-
-        def initialize(ctx:, manifest:, envelope_io:, bus:, store:, authorizer:, hook_context:) # rubocop:disable Metrics/ParameterLists
-          @ctx          = ctx
-          @manifest     = manifest
-          @envelope_io  = envelope_io
-          @bus          = bus
-          @store        = store
-          @authorizer   = authorizer
-          @hook_context = hook_context
-        end
-
-        def run(key)
-          res = @manifest.resolver.resolve(key)
-          mentry = res.entry
-          path = res.path
-          remaining = res.remaining
-          raise UsageError.new("no intake declared for '#{key}'") unless mentry.is_a?(Textus::Manifest::Entry::Intake)
-
-          before_etag = File.exist?(path) ? Etag.for_file(path) : nil
-          result = fetch_with_bus(key, mentry, remaining)
-          persist_and_notify(key, mentry, result, before_etag)
-        end
-
-        private
-
-        def fetch_timeout_for(key)
-          rule = @manifest.rules_for(key)
-          rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
-        end
-
-        def fetch_with_bus(key, mentry, remaining)
-          callable = @bus.rpc_callable(:resolve_intake, mentry.handler)
-          @bus.publish(:refresh_started, ctx: @hook_context, key: key, mode: :sync)
-          call_intake(key, mentry, callable, remaining)
-        end
-
-        def call_intake(key, mentry, callable, remaining)
-          timeout = fetch_timeout_for(key)
-          Timeout.timeout(timeout) do
-            callable.call(
-              store: @store,
-              config: mentry.config,
-              args: { trigger_key: key, leaf_segments: remaining || [] },
-            )
-          end
-        rescue Timeout::Error
-          @bus.publish(:refresh_failed, ctx: @hook_context, key: key,
-                                        error_class: "Timeout::Error",
-                                        error_message: "intake '#{mentry.handler}' exceeded #{timeout}s")
-          raise UsageError.new("intake '#{mentry.handler}' exceeded #{timeout}s timeout")
-        rescue Textus::Error => e
-          @bus.publish(:refresh_failed, ctx: @hook_context, key: key, error_class: e.class.name,
-                                        error_message: e.message)
-          raise
-        rescue StandardError => e
-          @bus.publish(:refresh_failed, ctx: @hook_context, key: key, error_class: e.class.name,
-                                        error_message: e.message)
-          raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
-        end
-
-        def persist_and_notify(key, mentry, result, before_etag)
-          normalized = self.class.send(:normalize_action_result, result, format: mentry.format)
-          @authorizer.authorize_write!(mentry, role: @ctx.role)
-          envelope = @envelope_io.write(
-            key,
-            mentry: mentry,
-            payload: Textus::Application::Writes::EnvelopeIO::Payload.new(
-              meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
-            ),
-          )
-          change = detect_change(before_etag, envelope)
-          @bus.publish(:entry_refreshed, ctx: @hook_context, key: key, envelope: envelope, change: change) unless change == :unchanged
-          envelope
-        end
-
-        def detect_change(before_etag, envelope)
-          if before_etag.nil? then :created
-          elsif envelope.etag == before_etag then :unchanged
-          else :updated
-          end
-        end
-
-        def self.normalize_action_result(res, format:)
-          res = res.transform_keys(&:to_s) if res.is_a?(Hash)
-          res ||= {}
-          meta_val = res["_meta"]
-          body     = res["body"]
-          content  = res["content"]
-
-          case format
-          when "markdown" then { meta: meta_val || {}, body: body.to_s, content: nil }
-          when "text"     then { meta: {}, body: body.to_s, content: nil }
-          when "json", "yaml"
-            if !content.nil?
-              { meta: meta_val || {}, body: nil, content: content }
-            elsif !body.nil?
-              { meta: {}, body: body.to_s, content: nil }
-            else
-              raise Textus::UsageError.new("intake for #{format} returned neither content nor body")
-            end
-          else
-            raise Textus::UsageError.new("unknown format #{format.inspect}")
-          end
-        end
-        private_class_method :normalize_action_result
-      end
-    end
-  end
-end

data/lib/textus/application/writes/accept.rb

@@ -1,89 +0,0 @@
-require_relative "authority_gate"
-
-module Textus
-  module Application
-    module Writes
-      class Accept
-        include AuthorityGate
-
-        def initialize(ctx:, manifest:, file_store:, schemas:, envelope_io:, bus:, authorizer:, hook_context:) # rubocop:disable Metrics/ParameterLists
-          @ctx          = ctx
-          @manifest     = manifest
-          @file_store   = file_store
-          @schemas      = schemas
-          @envelope_io  = envelope_io
-          @bus          = bus
-          @authorizer   = authorizer
-          @hook_context = hook_context
-        end
-
-        def call(pending_key)
-          assert_accept_authority!("accept")
-
-          env = Textus::Application::Reads::Get.new(
-            ctx: @ctx, manifest: @manifest, file_store: @file_store,
-          ).call(pending_key)
-          proposal = env.meta["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
-          target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
-          action = proposal["action"] || "put"
-
-          evaluate_promotion!(env, target)
-
-          case action
-          when "put"
-            # Nested proposal "frontmatter" — the meta to write to the accepted
-            # target. Not related to the removed intake-handler legacy bridge.
-            target_meta = env.meta["frontmatter"] || {}
-            target_body = env.body
-            put_op.call(target, meta: target_meta, body: target_body)
-          when "delete"
-            delete_op.call(target)
-          else
-            raise ProposalError.new("unknown action: #{action}")
-          end
-
-          delete_op.call(pending_key)
-
-          @bus.publish(:proposal_accepted,
-                       ctx: @hook_context,
-                       key: pending_key,
-                       target_key: target)
-
-          { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
-        end
-
-        private
-
-        def put_op
-          @put_op ||= Textus::Application::Writes::Put.new(
-            ctx: @ctx, manifest: @manifest, envelope_io: @envelope_io,
-            bus: @bus, authorizer: @authorizer, hook_context: @hook_context
-          )
-        end
-
-        def delete_op
-          @delete_op ||= Textus::Application::Writes::Delete.new(
-            ctx: @ctx, manifest: @manifest, envelope_io: @envelope_io,
-            bus: @bus, authorizer: @authorizer, hook_context: @hook_context
-          )
-        end
-
-        def evaluate_promotion!(env, target_key)
-          rules = @manifest.rules_for(target_key)
-          promote = rules.promote
-          return if promote.nil? || promote.requires.empty?
-
-          policy = Textus::Application::Policy::Promotion.from_names(promote.requires)
-          result = policy.evaluate(
-            entry: env, schemas: @schemas, manifest: @manifest, role: @ctx.role,
-          )
-          return if result.ok?
-
-          raise ProposalError.new(
-            "promotion gate failed: #{result.reasons.join("; ")}",
-          )
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/writes/delete.rb

@@ -1,33 +0,0 @@
-module Textus
-  module Application
-    module Writes
-      class Delete
-        def initialize(ctx:, manifest:, envelope_io:, bus:, authorizer:, hook_context:)
-          @ctx          = ctx
-          @manifest     = manifest
-          @envelope_io  = envelope_io
-          @bus          = bus
-          @authorizer   = authorizer
-          @hook_context = hook_context
-        end
-
-        def call(key, if_etag: nil, suppress_events: false)
-          @manifest.validate_key!(key)
-          mentry = @manifest.resolver.resolve(key).entry
-
-          @authorizer.authorize_write!(mentry, role: @ctx.role)
-
-          @envelope_io.delete(key, mentry: mentry, if_etag: if_etag)
-
-          unless suppress_events
-            @bus.publish(:entry_deleted,
-                         ctx: @hook_context,
-                         key: key)
-          end
-
-          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/writes/mv.rb

@@ -1,105 +0,0 @@
-module Textus
-  module Application
-    module Writes
-      class Mv
-        def initialize(ctx:, manifest:, envelope_io:, bus:, authorizer:, hook_context:)
-          @ctx          = ctx
-          @manifest     = manifest
-          @envelope_io  = envelope_io
-          @bus          = bus
-          @authorizer   = authorizer
-          @hook_context = hook_context
-        end
-
-        def call(old_key, new_key, dry_run: false)
-          old_res, new_res = prepare(old_key, new_key)
-          return dry_run_result(old_key, new_key, old_res, new_res) if dry_run
-
-          ensure_uid!(old_key, old_res.entry)
-          envelope = @envelope_io.move(
-            from_key: old_key, to_key: new_key,
-            new_mentry: new_res.entry
-          )
-          publish_renamed(old_key, new_key, envelope)
-          success_result(old_key, new_key, old_res, new_res, envelope)
-        end
-
-        private
-
-        def prepare(old_key, new_key)
-          @manifest.validate_key!(old_key)
-          @manifest.validate_key!(new_key)
-          raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
-
-          old_res = @manifest.resolver.resolve(old_key)
-          new_res = @manifest.resolver.resolve(new_key)
-          raise UnknownKey.new(old_key) unless @envelope_io.exists?(old_res.path)
-
-          validate_zone_and_format!(old_res.entry, new_res.entry)
-          @authorizer.authorize_write!(old_res.entry, role: @ctx.role)
-          @authorizer.authorize_write!(new_res.entry, role: @ctx.role)
-          raise UsageError.new("mv: target '#{new_key}' already exists at #{new_res.path}") if @envelope_io.exists?(new_res.path)
-
-          [old_res, new_res]
-        end
-
-        def validate_zone_and_format!(old_mentry, new_mentry)
-          if old_mentry.zone != new_mentry.zone
-            raise UsageError.new(
-              "mv: cross-zone move refused (#{old_mentry.zone} → #{new_mentry.zone}). " \
-              "Use put+delete for cross-zone moves.",
-            )
-          end
-          return if old_mentry.format == new_mentry.format
-
-          raise UsageError.new("mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.")
-        end
-
-        # If the source file lacks a UID, rewrite it in-place via EnvelopeIO#write
-        # so a UID gets injected before the move. This replaces the previous
-        # Put(suppress_events: true) bypass with a direct EnvelopeIO call —
-        # producing one "put" audit row, then the "mv" row from EnvelopeIO#move.
-        def ensure_uid!(old_key, old_mentry)
-          pre_env = @envelope_io.read_envelope(old_key)
-          return if pre_env.uid
-
-          @envelope_io.write(
-            old_key, mentry: old_mentry,
-                     payload: EnvelopeIO::Payload.new(
-                       meta: pre_env.meta, body: pre_env.body, content: pre_env.content,
-                     )
-          )
-        end
-
-        def publish_renamed(old_key, new_key, envelope)
-          @bus.publish(:entry_renamed,
-                       ctx: @hook_context,
-                       key: new_key,
-                       from_key: old_key,
-                       to_key: new_key,
-                       envelope: envelope)
-        end
-
-        def dry_run_result(old_key, new_key, old_res, new_res)
-          pre_env = @envelope_io.read_envelope(old_key)
-          {
-            "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
-            "from_key" => old_key, "to_key" => new_key,
-            "from_path" => old_res.path, "to_path" => new_res.path,
-            "uid" => pre_env.uid
-          }
-        end
-
-        def success_result(old_key, new_key, old_res, new_res, envelope)
-          {
-            "protocol" => PROTOCOL, "ok" => true,
-            "from_key" => old_key, "to_key" => new_key,
-            "from_path" => old_res.path, "to_path" => new_res.path,
-            "uid" => envelope.uid,
-            "envelope" => envelope.to_h_for_wire
-          }
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/writes/publish.rb

@@ -1,162 +0,0 @@
-module Textus
-  module Application
-    module Writes
-      # Single-pass publish use case: materializes Derived entries (template +
-      # projection + external runner) AND copies Leaf/Nested entries to their
-      # publish targets. Replaces the former two-step Build + Publish split.
-      #
-      # Return shape: { "protocol", "built", "published_leaves" }
-      # — wire-compatible with what the `textus build` CLI verb previously
-      #   assembled by merging Build + old Publish results.
-      class Publish
-        def initialize(ctx:, manifest:, file_store:, bus:, root:, store:, hook_context:) # rubocop:disable Metrics/ParameterLists
-          @ctx          = ctx
-          @manifest     = manifest
-          @file_store   = file_store
-          @bus          = bus
-          @root         = root
-          @store        = store
-          @hook_context = hook_context
-        end
-
-        def call(prefix: nil)
-          built  = []
-          leaves = []
-          repo_root = File.dirname(@root)
-
-          @manifest.entries.each do |mentry|
-            next if prefix && !entry_matches_prefix?(mentry, prefix)
-
-            case mentry
-            when Textus::Manifest::Entry::Derived
-              next unless mentry.in_generator_zone?
-
-              result = materialize_derived(mentry, repo_root)
-              built << result if result
-            when Textus::Manifest::Entry::Nested
-              next unless mentry.publish_each
-
-              publish_nested(mentry, repo_root, prefix, leaves)
-            when Textus::Manifest::Entry::Leaf
-              next if Array(mentry.publish_to).empty?
-
-              result = publish_leaf_entry(mentry, repo_root)
-              built << result if result
-            end
-          end
-
-          { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves }
-        end
-
-        private
-
-        # Materialize a Derived entry and copy to publish_to targets.
-        def materialize_derived(mentry, repo_root)
-          target_path = Materializer.new(
-            ctx: @ctx, manifest: @manifest, file_store: @file_store,
-            bus: @bus, root: @root, store: @store
-          ).run(mentry)
-
-          publish_derived_copies(mentry, target_path, repo_root)
-          fire_build_completed(mentry)
-
-          { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
-        end
-
-        def publish_derived_copies(mentry, target_path, repo_root)
-          envelope = reader.call(mentry.key)
-          mentry.publish_to.each do |rel|
-            target_abs = File.join(repo_root, rel)
-            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: @root)
-            publish_event(:file_published,
-                          key: mentry.key,
-                          envelope: envelope,
-                          source: target_path,
-                          target: target_abs)
-          end
-        end
-
-        def fire_build_completed(mentry)
-          envelope = reader.call(mentry.key)
-          src = mentry.source
-          selects = src.is_a?(Textus::Manifest::Entry::Derived::Projection) ? Array(src.select).compact : []
-          publish_event(:build_completed,
-                        key: mentry.key,
-                        envelope: envelope,
-                        sources: selects)
-        end
-
-        # Publish each leaf under a Nested entry's publish_each pattern.
-        def publish_nested(mentry, repo_root, prefix, accumulator)
-          @manifest.resolver.enumerate(prefix: mentry.key).each do |row|
-            next unless row[:manifest_entry].equal?(mentry)
-            next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-            accumulator << publish_nested_leaf(mentry, row, repo_root)
-          end
-        end
-
-        def publish_nested_leaf(mentry, row, repo_root)
-          target_rel = mentry.publish_target_for(row[:key])
-          target_abs = File.expand_path(File.join(repo_root, target_rel))
-          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
-            raise PublishError.new(
-              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-            )
-          end
-
-          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: @root)
-          publish_event(:file_published,
-                        key: row[:key],
-                        envelope: reader.call(row[:key]),
-                        source: row[:path],
-                        target: target_abs)
-          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
-        end
-
-        # Publish a standalone Leaf entry that has publish_to targets.
-        def publish_leaf_entry(mentry, repo_root)
-          source_path = @manifest.resolver.resolve(mentry.key).path
-          envelope = reader.call(mentry.key)
-
-          mentry.publish_to.each do |rel|
-            target_abs = File.join(repo_root, rel)
-            Textus::Infra::Publisher.publish(source: source_path, target: target_abs, store_root: @root)
-            publish_event(:file_published,
-                          key: mentry.key,
-                          envelope: envelope,
-                          source: source_path,
-                          target: target_abs)
-          end
-
-          { "key" => mentry.key, "path" => source_path, "published_to" => mentry.publish_to }
-        end
-
-        # Whether the entry should be processed for the given prefix filter.
-        def entry_matches_prefix?(mentry, prefix)
-          return true unless prefix
-
-          case mentry
-          when Textus::Manifest::Entry::Nested
-            # Nested: process if the entry key is a prefix of `prefix` or
-            # `prefix` is a prefix of the entry key (a leaf under it).
-            mentry.key.start_with?(prefix) ||
-              prefix.start_with?("#{mentry.key}.")
-          else
-            mentry.key.start_with?(prefix)
-          end
-        end
-
-        def reader
-          @reader ||= Textus::Application::Reads::Get.new(
-            ctx: @ctx, manifest: @manifest, file_store: @file_store,
-          )
-        end
-
-        def publish_event(event, **payload)
-          @bus.publish(event, ctx: @hook_context, **payload)
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/writes/put.rb

@@ -1,37 +0,0 @@
-module Textus
-  module Application
-    module Writes
-      class Put
-        def initialize(ctx:, manifest:, envelope_io:, bus:, authorizer:, hook_context:)
-          @ctx          = ctx
-          @manifest     = manifest
-          @envelope_io  = envelope_io
-          @bus          = bus
-          @authorizer   = authorizer
-          @hook_context = hook_context
-        end
-
-        def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
-          @manifest.validate_key!(key)
-          mentry = @manifest.resolver.resolve(key).entry
-
-          @authorizer.authorize_write!(mentry, role: @ctx.role)
-
-          envelope = @envelope_io.write(
-            key,
-            mentry: mentry,
-            payload: Textus::Application::Writes::EnvelopeIO::Payload.new(meta: meta, body: body, content: content),
-            if_etag: if_etag,
-          )
-
-          @bus.publish(:entry_put,
-                       ctx: @hook_context,
-                       key: key,
-                       envelope: envelope)
-
-          envelope
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/writes/reject.rb

@@ -1,50 +0,0 @@
-require_relative "authority_gate"
-
-module Textus
-  module Application
-    module Writes
-      class Reject
-        include AuthorityGate
-
-        def initialize(ctx:, manifest:, file_store:, envelope_io:, bus:, authorizer:, hook_context:) # rubocop:disable Metrics/ParameterLists
-          @ctx          = ctx
-          @manifest     = manifest
-          @file_store   = file_store
-          @envelope_io  = envelope_io
-          @bus          = bus
-          @authorizer   = authorizer
-          @hook_context = hook_context
-        end
-
-        def call(pending_key)
-          assert_accept_authority!("reject")
-
-          mentry = @manifest.resolver.resolve(pending_key).entry
-          unless mentry.in_proposal_zone?
-            raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})")
-          end
-
-          env = Textus::Application::Reads::Get.new(
-            ctx: @ctx, manifest: @manifest, file_store: @file_store,
-          ).call(pending_key)
-          proposal = env.meta&.dig("proposal") or
-            raise ProposalError.new("entry has no proposal block: #{pending_key}")
-          target_key = proposal["target_key"] or
-            raise ProposalError.new("proposal missing target_key")
-
-          Textus::Application::Writes::Delete.new(
-            ctx: @ctx, manifest: @manifest, envelope_io: @envelope_io,
-            bus: @bus, authorizer: @authorizer, hook_context: @hook_context
-          ).call(pending_key, suppress_events: true)
-
-          @bus.publish(:proposal_rejected,
-                       ctx: @hook_context,
-                       key: pending_key,
-                       target_key: target_key)
-
-          { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb/intro.rb

@@ -1,13 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Intro < Verb
-        command_name "intro"
-
-        def call(store)
-          emit(Textus::Intro.run(store))
-        end
-      end
-    end
-  end
-end

data/lib/textus/infra/event_bus.rb

@@ -1,27 +0,0 @@
-module Textus
-  module Infra
-    class EventBus
-      def initialize(bus:)
-        @bus = bus
-      end
-
-      def publish(event, **payload)
-        @bus.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/manifest/entry/validators/inject_intro.rb

@@ -1,21 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module InjectIntro
-          def self.call(entry)
-            inject_intro = entry.respond_to?(:inject_intro) ? entry.inject_intro : false
-            return unless inject_intro
-
-            raise UsageError.new("entry '#{entry.key}': inject_intro: is only valid on derived entries") unless entry.in_generator_zone?
-
-            has_template = entry.respond_to?(:template) && !entry.template.nil?
-            return if has_template
-
-            raise UsageError.new("entry '#{entry.key}': inject_intro: requires a template:")
-          end
-        end
-      end
-    end
-  end
-end