textus 0.22.0 → 0.29.0

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -0,0 +1,46 @@
+module Textus
+  module Maintenance
+    # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
+    # Calls Write::Mv directly for each entry — emits one audit row per file moved.
+    class KeyMvPrefix
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+      end
+
+      def call(from_prefix:, to_prefix:, dry_run: false)
+        raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
+
+        leaves = list_leaves_under(from_prefix)
+        warnings = []
+        warnings << "no keys under #{from_prefix}" if leaves.empty?
+
+        steps = leaves.map do |old_key|
+          tail = old_key.delete_prefix("#{from_prefix}.")
+          new_key = "#{to_prefix}.#{tail}"
+          { "op" => "mv", "from" => old_key, "to" => new_key }
+        end
+
+        plan = Plan.new(steps: steps, warnings: warnings)
+        return plan if dry_run
+
+        steps.each do |s|
+          mv.call(s["from"], s["to"], dry_run: false)
+        end
+        plan
+      end
+
+      private
+
+      def list_leaves_under(prefix)
+        Read::List.new(container: @container)
+                  .call(prefix: prefix)
+                  .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+      end
+
+      def mv
+        Write::Mv.new(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/maintenance/migrate.rb

@@ -0,0 +1,51 @@
+require "yaml"
+
+module Textus
+  module Maintenance
+    # Loads a YAML migration plan and dispatches each op to the
+    # appropriate Maintenance use case. Concatenates resulting Plans.
+    class Migrate
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+      end
+
+      def call(plan_yaml:, dry_run: false)
+        raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
+        raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
+
+        ops = Array(raw["operations"])
+        all_steps = []
+        warnings = []
+
+        ops.each do |op_hash|
+          op_name = op_hash["op"]
+          sub_plan = invoke_op(op_name, op_hash, dry_run: dry_run)
+          all_steps.concat(sub_plan.steps)
+          warnings.concat(sub_plan.warnings)
+        end
+
+        Plan.new(steps: all_steps, warnings: warnings)
+      end
+
+      private
+
+      def invoke_op(op_name, op_hash, dry_run:)
+        kwargs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
+        klass = op_class(op_name)
+        klass.new(
+          container: @container, call: @call,
+        ).call(**kwargs)
+      end
+
+      def op_class(op_name)
+        case op_name
+        when "key_mv_prefix"     then KeyMvPrefix
+        when "key_delete_prefix" then KeyDeletePrefix
+        when "zone_mv"           then ZoneMv
+        else raise UsageError.new("unknown op: #{op_name}")
+        end
+      end
+    end
+  end
+end

data/lib/textus/maintenance/rule_lint.rb

@@ -0,0 +1,56 @@
+require "yaml"
+
+module Textus
+  module Maintenance
+    # Compare the live manifest's `rules:` block against a candidate
+    # YAML string. Returns a Plan describing rule additions/removals/
+    # changes. Does NOT write anything.
+    class RuleLint
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @root      = container.root
+      end
+
+      def call(candidate_yaml:)
+        live_rules      = current_rules
+        candidate_rules = parse_candidate(candidate_yaml)
+
+        live_by_match      = live_rules.to_h { |r| [r["match"], r] }
+        candidate_by_match = candidate_rules.to_h { |r| [r["match"], r] }
+
+        steps = (candidate_by_match.keys - live_by_match.keys).map do |m|
+          { "op" => "add_rule", "match" => m, "rule" => candidate_by_match[m] }
+        end
+        (live_by_match.keys - candidate_by_match.keys).each do |m|
+          steps << { "op" => "remove_rule", "match" => m }
+        end
+        (live_by_match.keys & candidate_by_match.keys).each do |m|
+          next if live_by_match[m] == candidate_by_match[m]
+
+          steps << { "op" => "change_rule", "match" => m,
+                     "from" => live_by_match[m], "to" => candidate_by_match[m] }
+        end
+
+        Plan.new(steps: steps, warnings: [])
+      end
+
+      private
+
+      def current_rules
+        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/maintenance/zone_mv.rb

@@ -0,0 +1,51 @@
+require "yaml"
+
+module Textus
+  module Maintenance
+    # Rename a zone — rewrites the manifest's zones[] entry, rewrites
+    # the `zone:` field on every entry under the old zone, and moves
+    # every file from zones/<old>/ to zones/<new>/.
+    class ZoneMv
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+        @root      = container.root
+      end
+
+      def call(from:, to:, dry_run: false)
+        raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
+        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.zones.key?(from)
+
+        dest_dir = File.join(@root, "zones", to)
+        raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)
+
+        affected_keys = @manifest.data.entries.select { |e| e.zone == from }.map(&:key)
+
+        steps  = [{ "op" => "rename_zone", "from" => from, "to" => to }]
+        steps += affected_keys.map { |k| { "op" => "mv", "from" => k, "to" => "#{to}#{k[from.length..]}" } }
+
+        plan = Plan.new(steps: steps, warnings: [])
+        return plan if dry_run
+
+        rewrite_manifest!(from, to)
+        FileUtils.mv(File.join(@root, "zones", from), dest_dir)
+        plan
+      end
+
+      private
+
+      def rewrite_manifest!(from, to)
+        path = File.join(@root, "manifest.yaml")
+        raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+        raw["zones"].each { |z| z["name"] = to if z["name"] == from }
+        raw["entries"].each do |e|
+          e["zone"] = to if e["zone"] == from
+          e["key"]  = e["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
+          e["path"] = e["path"].sub(%r{\A#{Regexp.escape(from)}(/|\z)}, "#{to}\\1")
+        end
+        File.write(path, YAML.dump(raw))
+      end
+    end
+  end
+end

data/lib/textus/maintenance.rb

@@ -0,0 +1,15 @@
+module Textus
+  # Bulk and structural changes to a textus store. Each use case returns
+  # a Plan when called with dry_run: true, and applies the plan when
+  # called with dry_run: false.
+  module Maintenance
+    # A Plan is a JSON-shaped preview. Steps are op-tagged hashes the
+    # use case knows how to apply. Warnings are strings surfaced to
+    # the operator (skipped keys, ambiguities).
+    Plan = Data.define(:steps, :warnings) do
+      def to_h
+        { "steps" => steps, "warnings" => warnings }
+      end
+    end
+  end
+end

data/lib/textus/manifest/data.rb

@@ -0,0 +1,79 @@
+require_relative "schema"
+require_relative "role_kinds"
+
+module Textus
+  class Manifest
+    # Immutable, parsed view of a manifest YAML document.
+    #
+    # Holds raw structural data (zones, entries, audit_config, role_mapping)
+    # but no behaviour beyond accessors. Behaviour (zone authority, key
+    # resolution, rules) lives on Manifest::Policy / Resolver / Rules.
+    class Data
+      AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
+
+      attr_reader :raw, :root, :entries, :zones, :zone_readers, :audit_config, :role_mapping, :policy
+
+      def self.validate_key!(key)
+        raise UsageError.new("empty key") if key.nil? || key.empty?
+
+        Key::Grammar.validate!(key)
+      end
+
+      # Forwarder used by Resolver and Entry classes that received a Data
+      # but were written against the historical Manifest API.
+      def validate_key!(key) = self.class.validate_key!(key)
+
+      def self.parse(raw, root:)
+        raise BadFrontmatter.new(File.join(root.to_s, "manifest.yaml"), "manifest must declare zones:") if Array(raw["zones"]).empty?
+
+        Schema.validate!(raw)
+        new(raw: raw, root: root)
+      end
+
+      def initialize(raw:, root:)
+        @raw = raw
+        @root = root
+        @zones = Array(raw["zones"]).to_h { |z| [z["name"], Array(z["write_policy"])] }
+        @zone_readers = Array(raw["zones"]).to_h do |z|
+          rp = z["read_policy"]
+          [z["name"], rp.nil? ? :all : Array(rp)]
+        end
+        @audit_config = build_audit_config(raw)
+        @role_mapping = RoleKinds.resolve(raw["roles"])
+        # Policy is constructed before entries because Entry validators
+        # call `entry.in_generator_zone?(policy)` and similar helpers
+        # that take Policy as an argument.
+        @policy = Policy.new(self)
+        @entries = build_entries(raw)
+        validate_declared_keys!
+        freeze
+      end
+
+      private
+
+      def build_audit_config(raw)
+        a = raw["audit"] || {}
+        {
+          max_size: a["max_size"] || AUDIT_DEFAULTS[:max_size],
+          keep: a["keep"] || AUDIT_DEFAULTS[:keep],
+        }.freeze
+      end
+
+      def build_entries(raw)
+        Array(raw["entries"]).map do |e|
+          entry = Manifest::Entry::Parser.call(e)
+          Manifest::Entry::Validators.run_all(entry, policy: @policy)
+          entry
+        end.freeze
+      end
+
+      def validate_declared_keys!
+        @entries.each do |e|
+          raise UsageError.new("empty key") if e.key.nil? || e.key.empty?
+
+          Key::Grammar.validate!(e.key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/base.rb

@@ -2,11 +2,10 @@ module Textus
   class Manifest
     class Entry
       class Base < Entry
-        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :manifest, :publish_to
+        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :publish_to
 
         # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
-        def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, format:, publish_to: [])
-          @manifest = manifest
+        def initialize(raw:, key:, path:, zone:, schema:, owner:, format:, publish_to: [])
           @raw = raw
           @key = key
           @path = path
@@ -18,14 +17,14 @@ module Textus
         end
         # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
 
-        def zone_writers
-          @manifest.zone_writers(@zone)
+        def zone_writers(policy)
+          policy.zone_writers(@zone)
         rescue UsageError => e
           raise UsageError.new("entry '#{@key}': #{e.message}")
         end
 
-        def in_generator_zone? = @manifest.zone_kinds(@zone).include?(:generator)
-        def in_proposal_zone?  = @manifest.zone_kinds(@zone).include?(:proposer)
+        def in_generator_zone?(policy) = policy.zone_kinds(@zone).include?(:generator)
+        def in_proposal_zone?(policy)  = policy.zone_kinds(@zone).include?(:proposer)
 
         def nested?  = false
         def derived? = false
@@ -41,11 +40,32 @@ module Textus
         def publish_each   = nil
         def index_filename = nil
 
-        PublishContext = Struct.new(
-          :repo_root, :manifest, :file_store, :root, :store, :ctx, :bus, :hook_context,
-          :reader, :emit, # callables: reader.call(key) → envelope; emit.call(event, **payload)
-          keyword_init: true
-        )
+        # Minimal context object passed into entry `publish_via` hooks.
+        # Everything beyond the three primitives is derived. Data.define
+        # instances are frozen, so we recompute per-call rather than
+        # memoizing — RoleScope/Hooks::Context construction is cheap.
+        PublishContext = ::Data.define(:container, :call, :reader) do
+          def manifest   = container.manifest
+          def root       = container.root
+          def repo_root  = File.dirname(container.root)
+          def events     = container.events
+
+          def hook_context
+            Textus::Hooks::Context.new(scope: scope_for_hooks)
+          end
+
+          def emit(event, **payload)
+            events.publish(event, ctx: hook_context, **payload)
+          end
+
+          private
+
+          def scope_for_hooks
+            Textus::RoleScope.new(
+              container: container, role: call.role, dry_run: call.dry_run,
+            )
+          end
+        end
 
         # Subclasses override to customize publish behavior.
         # Default: copy the stored file to each publish_to target.
@@ -59,12 +79,12 @@ module Textus
 
           publish_to.each do |rel|
             target_abs = File.join(pctx.repo_root, rel)
-            Textus::Infra::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
-            pctx.emit.call(:file_published,
-                           key: @key,
-                           envelope: envelope,
-                           source: source_path,
-                           target: target_abs)
+            Textus::Ports::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published,
+                      key: @key,
+                      envelope: envelope,
+                      source: source_path,
+                      target: target_abs)
           end
 
           { kind: :built, value: { "key" => @key, "path" => source_path, "published_to" => publish_to } }

data/lib/textus/manifest/entry/derived.rb

@@ -2,8 +2,8 @@ module Textus
   class Manifest
     class Entry
       class Derived < Base
-        Projection = Data.define(:select, :pluck, :sort_by, :transform)
-        External   = Data.define(:sources, :runner)
+        Projection = ::Data.define(:select, :pluck, :sort_by, :transform)
+        External   = ::Data.define(:sources, :runner)
 
         attr_reader :source, :template, :inject_boot, :events
 
@@ -20,23 +20,22 @@ module Textus
         def external?   = @source.is_a?(External)
 
         def publish_via(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-          return nil unless in_generator_zone?
+          return nil unless in_generator_zone?(pctx.manifest.policy)
 
-          target_path = Textus::Application::Writes::Materializer.new(
-            ctx: pctx.ctx, manifest: pctx.manifest, file_store: pctx.file_store,
-            bus: pctx.bus, root: pctx.root, store: pctx.store
+          target_path = Textus::Write::Materializer.new(
+            container: pctx.container, call: pctx.call,
           ).run(self)
 
           envelope = pctx.reader.call(@key)
           Array(publish_to).each do |rel|
             target_abs = File.join(pctx.repo_root, rel)
-            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: pctx.root)
-            pctx.emit.call(:file_published, key: @key, envelope: envelope, source: target_path, target: target_abs)
+            Textus::Ports::Publisher.publish(source: target_path, target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published, key: @key, envelope: envelope, source: target_path, target: target_abs)
           end
 
           src = @source
           selects = src.is_a?(Projection) ? Array(src.select).compact : []
-          pctx.emit.call(:build_completed, key: @key, envelope: envelope, sources: selects)
+          pctx.emit(:build_completed, key: @key, envelope: envelope, sources: selects)
 
           { kind: :built, value: { "key" => @key, "path" => target_path, "published_to" => publish_to } }
         end

data/lib/textus/manifest/entry/nested.rb

@@ -1,5 +1,3 @@
-require_relative "validators/publish_each"
-
 module Textus
   class Manifest
     class Entry
@@ -37,7 +35,7 @@ module Textus
           return nil if @publish_each.nil?
 
           leaves = []
-          @manifest.resolver.enumerate(prefix: @key).each do |row|
+          pctx.manifest.resolver.enumerate(prefix: @key).each do |row|
             next unless row[:manifest_entry].equal?(self)
             next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
 
@@ -49,12 +47,12 @@ module Textus
               )
             end
 
-            Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
-            pctx.emit.call(:file_published,
-                           key: row[:key],
-                           envelope: pctx.reader.call(row[:key]),
-                           source: row[:path],
-                           target: target_abs)
+            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published,
+                      key: row[:key],
+                      envelope: pctx.reader.call(row[:key]),
+                      source: row[:path],
+                      target: target_abs)
             leaves << { "key" => row[:key], "source" => row[:path], "target" => target_abs }
           end
 

data/lib/textus/manifest/entry/parser.rb

@@ -4,7 +4,7 @@ module Textus
       module Parser
         COMPUTE_KINDS = %w[projection external].freeze
 
-        def self.call(manifest, raw)
+        def self.call(raw)
           key = raw["key"] or raise UsageError.new("manifest entry missing key")
           path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
           zone = raw["zone"] or raise UsageError.new("manifest entry '#{key}' missing zone")
@@ -14,7 +14,7 @@ module Textus
           format = resolve_format(raw, path)
 
           common = {
-            manifest: manifest, raw: raw,
+            raw: raw,
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
             format: format,

data/lib/textus/manifest/entry/validators/events.rb

@@ -3,8 +3,8 @@ module Textus
     class Entry
       module Validators
         module Events
-          def self.call(entry)
-            pubsub_events = Textus::Hooks::Bus::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
+            pubsub_events = Textus::Hooks::EventBus::EVENTS.keys
             events = entry.events
             events.each_key do |evt|
               next if pubsub_events.include?(evt.to_sym)

data/lib/textus/manifest/entry/validators/format_matrix.rb

@@ -3,7 +3,7 @@ module Textus
     class Entry
       module Validators
         module FormatMatrix
-          def self.call(entry)
+          def self.call(entry, policy:)
             begin
               Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested?)
             rescue UsageError => e
@@ -17,7 +17,7 @@ module Textus
             has_template = !entry.template.nil?
             is_external  = entry.derived? && entry.external?
             is_intake    = entry.intake?
-            return unless entry.in_generator_zone? && !has_template && !is_external && !is_intake &&
+            return unless entry.in_generator_zone?(policy) && !has_template && !is_external && !is_intake &&
                           %w[markdown text].include?(entry.format) && !entry.nested?
 
             raise UsageError.new("entry '#{entry.key}': #{entry.format} entries in a generator zone require a template")

data/lib/textus/manifest/entry/validators/index_filename.rb

@@ -3,7 +3,7 @@ module Textus
     class Entry
       module Validators
         module IndexFilename
-          def self.call(entry)
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
             index_filename = entry.nested? ? entry.index_filename : entry.raw["index_filename"]
             return if index_filename.nil?

data/lib/textus/manifest/entry/validators/inject_boot.rb

@@ -3,10 +3,12 @@ module Textus
     class Entry
       module Validators
         module InjectBoot
-          def self.call(entry)
+          def self.call(entry, policy:)
             return unless entry.inject_boot
 
-            raise UsageError.new("entry '#{entry.key}': inject_boot: is only valid on derived entries") unless entry.in_generator_zone?
+            unless entry.in_generator_zone?(policy)
+              raise UsageError.new("entry '#{entry.key}': inject_boot: is only valid on derived entries")
+            end
 
             return unless entry.template.nil?
 

data/lib/textus/manifest/entry/validators/publish_each.rb

@@ -7,7 +7,7 @@ module Textus
           VAR_RE = /\{([a-z]+)\}/
           REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
 
-          def self.call(entry)
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
             publish_each = entry.nested? ? entry.publish_each : entry.raw["publish_each"]
             return if publish_each.nil?

data/lib/textus/manifest/entry/validators.rb

@@ -10,8 +10,8 @@ module Textus
           FormatMatrix,
         ].freeze
 
-        def self.run_all(entry)
-          REGISTERED.each { |v| v.call(entry) }
+        def self.run_all(entry, policy:)
+          REGISTERED.each { |v| v.call(entry, policy: policy) }
           nil
         end
       end

data/lib/textus/manifest/entry.rb

@@ -1,11 +1,6 @@
 module Textus
   class Manifest
     class Entry
-      # Re-exported for backward compatibility with callers that referenced these
-      # constants on Entry. Canonical source is the PublishEach validator.
-      PUBLISH_EACH_VARS = Validators::PublishEach::KNOWN_VARS
-      PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
-
       # Populated by each Entry::* subclass at load time.
       REGISTRY = {}
     end

data/lib/textus/manifest/policy.rb

@@ -0,0 +1,48 @@
+module Textus
+  class Manifest
+    # Authority over zones and roles derived from a Manifest::Data snapshot.
+    # Encapsulates the lookups previously living on Manifest itself
+    # (zone_writers, zone_kinds, permission_for, role_kind, roles_with_kind).
+    class Policy
+      def initialize(data)
+        @data = data
+        @zone_kinds_cache = {}
+      end
+
+      def zone_writers(zone_name)
+        @data.zones[zone_name] or raise UsageError.new("undeclared zone '#{zone_name}'")
+      end
+
+      def zone_readers
+        @data.zone_readers
+      end
+
+      def permission_for(zone_name)
+        Textus::Domain::Permission.new(
+          zone: zone_name,
+          write_policy: zone_writers(zone_name),
+          read_policy: @data.zone_readers[zone_name] || :all,
+        )
+      end
+
+      def zone_kinds(zone_name)
+        @zone_kinds_cache[zone_name] ||= zone_writers(zone_name).each_with_object(Set.new) do |w, acc|
+          k = role_kind(w)
+          acc << k if k
+        end.freeze
+      end
+
+      def role_mapping
+        @data.role_mapping
+      end
+
+      def role_kind(name)
+        @data.role_mapping[name]
+      end
+
+      def roles_with_kind(kind)
+        @data.role_mapping.each_with_object([]) { |(name, k), acc| acc << name if k == kind }
+      end
+    end
+  end
+end