textus 0.15.0 → 0.20.0

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

@@ -1,38 +1,102 @@
 module Textus
   module Application
     module Writes
-      # Copies nested-leaf entries to their `publish_each:` targets. Fires
-      # `:file_published` for each copy. Mirror of `Build` for the publish
-      # half — split out from the old Build per ADR 0007.
+      # 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:, bus:)
-          @ctx = ctx
-          @bus = bus
+        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)
-          repo_root = File.dirname(store.root)
-          out = []
-          manifest.entries.each do |mentry|
-            next unless mentry.nested && mentry.publish_each
-            next if prefix && !mentry.key.start_with?(prefix) && !prefix.start_with?("#{mentry.key}.")
+          built  = []
+          leaves = []
+          repo_root = File.dirname(@root)
 
-            manifest.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
+          @manifest.entries.each do |mentry|
+            next if prefix && !entry_matches_prefix?(mentry, prefix)
 
-              out << publish_leaf(mentry, row, repo_root)
+            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, "published_leaves" => out }
+
+          { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves }
         end
 
         private
 
-        def store = @ctx.store
-        def manifest = store.manifest
+        # 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)
 
-        def publish_leaf(mentry, row, repo_root)
+          publish_derived_copies(mentry, target_path, repo_root)
+          fire_build_completed(mentry, target_path)
+
+          { "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, target_path) # rubocop:disable Lint/UnusedMethodArgument
+          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)
@@ -41,16 +105,57 @@ module Textus
             )
           end
 
-          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: store.root)
-          @bus.publish(:file_published,
-                       store: @ctx.with_role(@ctx.role),
-                       key: row[:key],
-                       envelope: store.reader.get(row[:key]),
-                       source: row[:path],
-                       target: target_abs,
-                       correlation_id: @ctx.correlation_id)
+          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

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

@@ -2,35 +2,32 @@ module Textus
   module Application
     module Writes
       class Put
-        def initialize(ctx:, bus:)
-          @ctx = ctx
-          @bus = bus
+        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, suppress_events: false)
-          @ctx.store.manifest.validate_key!(key)
-          mentry, = @ctx.store.manifest.resolve(key)
+        def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
+          @manifest.validate_key!(key)
+          mentry = @manifest.resolver.resolve(key).entry
 
-          unless @ctx.can_write?(mentry.zone)
-            raise WriteForbidden.new(key, mentry.zone,
-                                     writers: @ctx.store.manifest.zone_writers(mentry.zone))
-          end
+          @authorizer.authorize_write!(mentry, role: @ctx.role)
 
-          envelope = @ctx.store.writer.write_envelope_to_disk(
+          envelope = @envelope_io.write(
             key,
             mentry: mentry,
-            payload: Textus::Store::Writer::Payload.new(meta: meta, body: body, content: content),
-            ctx: @ctx,
+            payload: Textus::Application::Writes::EnvelopeIO::Payload.new(meta: meta, body: body, content: content),
             if_etag: if_etag,
           )
 
-          unless suppress_events
-            @bus.publish(:entry_put,
-                         store: @ctx.with_role(@ctx.role),
-                         key: key,
-                         envelope: envelope,
-                         correlation_id: @ctx.correlation_id)
-          end
+          @bus.publish(:entry_put,
+                       ctx: @hook_context,
+                       key: key,
+                       envelope: envelope)
 
           envelope
         end

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

@@ -2,32 +2,41 @@ module Textus
   module Application
     module Writes
       class Reject
-        def initialize(ctx:, bus:)
-          @ctx = ctx
-          @bus = bus
+        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)
           raise ProposalError.new("only human role can reject proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
 
-          mentry, = @ctx.store.manifest.resolve(pending_key)
+          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 = @ctx.store.reader.get(pending_key)
+          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, bus: @bus).call(pending_key, suppress_events: true)
+          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,
-                       store: @ctx.with_role(@ctx.role),
+                       ctx: @hook_context,
                        key: pending_key,
-                       target_key: target_key,
-                       correlation_id: @ctx.correlation_id)
+                       target_key: target_key)
 
           { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
         end

data/lib/textus/builder/pipeline.rb

@@ -7,11 +7,15 @@ module Textus
       # Returns a new hash with _meta as the first key, per SPEC §6 ordering.
       def self.call(content_hash, mentry)
         meta = { "generated_at" => Time.now.utc.iso8601 }
-        from = Array(mentry.projection&.fetch("select", nil)).compact
-        meta["from"] = from unless from.empty?
+        if mentry.is_a?(Textus::Manifest::Entry::Derived)
+          src = mentry.source
+          if src.is_a?(Textus::Manifest::Entry::Derived::Projection)
+            from = Array(src.select).compact
+            meta["from"] = from unless from.empty?
+            meta["reduce"] = src.transform if src.transform
+          end
+        end
         meta["template"] = mentry.template if mentry.template
-        reduce = mentry.projection&.dig("transform")
-        meta["reduce"] = reduce if reduce
 
         out = { "_meta" => meta }
         content_hash.each { |k, v| out[k] = v unless k == "_meta" }
@@ -58,22 +62,23 @@ module Textus
         }
       end
 
-      def self.run(store:, mentry:, template_loader:)
+      # rubocop:disable Metrics/ParameterLists
+      def self.run(mentry:, manifest:, reader:, lister:, transform_resolver:, template_loader:,
+                   transform_context: nil, inject_intro: nil)
         # 1. Load sources + project + reduce
         data =
-          if mentry.projection
-            ops = Operations.for(store)
-            Projection.new(
-              reader: ops.reads.get.method(:call),
-              spec: mentry.projection,
-              lister: ops.reads.list.method(:call),
-              transform_resolver: ->(name) { store.registry.rpc_callable(:transform_rows, name) },
-              transform_context: Application::Context.system(store),
+          if mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
+            Application::Projection.new(
+              reader: reader,
+              spec: mentry.source.to_h.transform_keys(&:to_s),
+              lister: lister,
+              transform_resolver: transform_resolver,
+              transform_context: transform_context,
             ).run
           else
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end
-        data = data.merge("intro" => Intro.run(store)) if mentry.inject_intro
+        data = data.merge("intro" => inject_intro.call) if mentry.inject_intro && inject_intro
 
         # 2. Render
         klass = renderers[mentry.format] or
@@ -81,12 +86,13 @@ module Textus
         bytes = klass.new(template_loader: template_loader).call(mentry: mentry, data: data)
 
         # 3. Write (idempotent: skip if only generated_at would differ)
-        target_path = Key::Path.resolve(store.manifest, mentry)
+        target_path = Key::Path.resolve(manifest, mentry)
         FileUtils.mkdir_p(File.dirname(target_path))
         write_if_changed(target_path, bytes, mentry.format)
 
         target_path
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def self.write_if_changed(target_path, bytes, format)
         if File.exist?(target_path)

data/lib/textus/builder/renderer/json.rb

@@ -28,7 +28,10 @@ module Textus
         end
 
         def default_shape(mentry, data)
-          if mentry.projection && mentry.projection["transform"] && data.is_a?(Hash) && !data.key?("entries")
+          has_transform = mentry.is_a?(Textus::Manifest::Entry::Derived) &&
+                          mentry.source.is_a?(Textus::Manifest::Entry::Derived::Projection) &&
+                          mentry.source.transform
+          if has_transform && data.is_a?(Hash) && !data.key?("entries")
             data
           elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
             { "entries" => data["entries"] }

data/lib/textus/builder/renderer/markdown.rb

@@ -8,10 +8,16 @@ module Textus
           raise TemplateError.new("entry '#{mentry.key}': markdown build requires a template") unless mentry.template
 
           body = Mustache.render(@template_loader.call(mentry.template), data)
+          from = if mentry.is_a?(Textus::Manifest::Entry::Derived) &&
+                    mentry.source.is_a?(Textus::Manifest::Entry::Derived::Projection)
+                   Array(mentry.source.select).compact
+                 else
+                   []
+                 end
           frontmatter = {
             "generated" => {
               "at" => Time.now.utc.iso8601,
-              "from" => Array(mentry.projection&.fetch("select", nil)).compact,
+              "from" => from,
             },
           }
           Entry.for_format("markdown").serialize(meta: frontmatter, body: body)

data/lib/textus/builder/renderer/yaml.rb

@@ -28,7 +28,10 @@ module Textus
         end
 
         def default_shape(mentry, data)
-          if mentry.projection && mentry.projection["transform"] && data.is_a?(Hash) && !data.key?("entries")
+          has_transform = mentry.is_a?(Textus::Manifest::Entry::Derived) &&
+                          mentry.source.is_a?(Textus::Manifest::Entry::Derived::Projection) &&
+                          mentry.source.transform
+          if has_transform && data.is_a?(Hash) && !data.key?("entries")
             data
           elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
             { "entries" => data["entries"] }

data/lib/textus/cli/group/hook.rb

@@ -2,9 +2,7 @@ module Textus
   class CLI
     class Group
       class Hook < Group
-        self.cli_name = "hook"
-        subcommands["list"] = Verb::Hooks
-        subcommands["run"]  = Verb::HookRun
+        command_name "hook"
       end
     end
   end

data/lib/textus/cli/group/key.rb

@@ -2,10 +2,7 @@ module Textus
   class CLI
     class Group
       class Key < Group
-        self.cli_name = "key"
-        subcommands["mv"]      = Verb::Mv
-        subcommands["uid"]     = Verb::Uid
-        subcommands["normalize"] = Verb::KeyNormalize
+        command_name "key"
       end
     end
   end

data/lib/textus/cli/group/refresh.rb

@@ -2,8 +2,7 @@ module Textus
   class CLI
     class Group
       class Refresh < Group
-        self.cli_name = "refresh"
-        subcommands["stale"] = Verb::RefreshStale
+        command_name "refresh"
 
         def parse(argv)
           if argv.first == "stale"

data/lib/textus/cli/group/rule.rb

@@ -2,9 +2,7 @@ module Textus
   class CLI
     class Group
       class Rule < Group
-        self.cli_name = "rule"
-        subcommands["list"]    = Verb::RuleList
-        subcommands["explain"] = Verb::RuleExplain
+        command_name "rule"
       end
     end
   end

data/lib/textus/cli/group/schema.rb

@@ -2,11 +2,7 @@ module Textus
   class CLI
     class Group
       class Schema < Group
-        self.cli_name = "schema"
-        subcommands["show"]    = Verb::Schema
-        subcommands["init"]    = Verb::SchemaInit
-        subcommands["diff"]    = Verb::SchemaDiff
-        subcommands["migrate"] = Verb::SchemaMigrate
+        command_name "schema"
       end
     end
   end

data/lib/textus/cli/group.rb

@@ -2,19 +2,14 @@ module Textus
   class CLI
     class Group < Verb
       class << self
+        # Subcommands are auto-derived: any Verb descendant whose
+        # `parent_group` is this group counts as a subcommand. Sorted
+        # alphabetically by command_name for stable help output.
         def subcommands
-          @subcommands ||= {}
-        end
-
-        def cli_name
-          @cli_name || raise("subclass must define cli_name")
-        end
-
-        attr_writer :cli_name
-
-        def inherited(subclass)
-          super
-          subclass.instance_variable_set(:@subcommands, {})
+          Verb.descendants
+              .select { |k| k.parent_group == self && k.command_name }
+              .sort_by(&:command_name)
+              .to_h { |k| [k.command_name, k] }
         end
 
         def needs_store?
@@ -24,18 +19,19 @@ module Textus
       end
 
       def parse(argv)
+        subs = self.class.subcommands
         subname = argv.shift
         if subname.nil?
           raise UsageError.new(
-            "#{self.class.cli_name} requires a subcommand: #{self.class.subcommands.keys.join(", ")}",
+            "#{self.class.command_name} requires a subcommand: #{subs.keys.join(", ")}",
           )
         end
 
-        @sub_klass = self.class.subcommands[subname]
+        @sub_klass = subs[subname]
         unless @sub_klass
           raise UsageError.new(
-            "unknown #{self.class.cli_name} subcommand '#{subname}'. " \
-            "Valid: #{self.class.subcommands.keys.join(", ")}",
+            "unknown #{self.class.command_name} subcommand '#{subname}'. " \
+            "Valid: #{subs.keys.join(", ")}",
           )
         end
 

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

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Accept < Verb
+        command_name "accept"
+
         option :as_flag, "--as=ROLE"
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          emit(operations_for(store).writes.accept.call(key))
+          emit(operations_for(store).accept(key))
         end
       end
     end

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

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Audit < Verb
+        command_name "audit"
+
         option :key_filter, "--key=KEY"
         option :zone, "--zone=Z"
         option :role_filter, "--role=ROLE"
@@ -13,7 +15,7 @@ module Textus
         def call(store)
           ops = operations_for(store)
           since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ops.ctx.now)
-          rows = ops.reads.audit.call(
+          rows = ops.audit(
             key: key_filter,
             zone: zone,
             role: role_filter,

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

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Blame < Verb
+        command_name "blame"
+
         option :limit, "--limit=N"
 
         def call(store)
           key = positional.shift or raise UsageError.new("blame requires a key")
-          rows = operations_for(store).reads.blame.call(key: key, limit: limit&.to_i)
+          rows = operations_for(store).blame(key: key, limit: limit&.to_i)
           emit({ "verb" => "blame", "key" => key, "rows" => rows })
         end
       end

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

@@ -2,16 +2,15 @@ module Textus
   class CLI
     class Verb
       class Build < Verb
+        command_name "build"
+
         option :prefix, "--prefix=K"
 
         def call(store)
           Textus::Infra::BuildLock.with(root: store.root) do
             ops = Textus::Operations.for(store, role: "builder")
-            build_res   = ops.writes.build.call(prefix: prefix)
-            publish_res = ops.writes.publish.call(prefix: prefix)
-            emit({ "protocol" => Textus::PROTOCOL,
-                   "built" => build_res["built"],
-                   "published_leaves" => publish_res["published_leaves"] })
+            result = ops.publish(prefix: prefix)
+            emit(result)
           end
         end
       end

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

@@ -2,12 +2,14 @@ module Textus
   class CLI
     class Verb
       class Delete < Verb
+        command_name "delete"
+
         option :as_flag, "--as=ROLE"
         option :if_etag, "--if-etag=E"
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          emit(operations_for(store).writes.delete.call(key, if_etag: if_etag))
+          emit(operations_for(store).delete(key, if_etag: if_etag))
         end
       end
     end

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

@@ -2,9 +2,11 @@ module Textus
   class CLI
     class Verb
       class Deps < Verb
+        command_name "deps"
+
         def call(store)
           key = positional.shift or raise UsageError.new("deps requires a key")
-          emit({ "key" => key, "deps" => operations_for(store).reads.deps.call(key) })
+          emit({ "key" => key, "deps" => operations_for(store).deps(key) })
         end
       end
     end

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

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Doctor < Verb
+        command_name "doctor"
+
         option :checks, "--check=NAME"
 
         def call(store)

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

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Freshness < Verb
+        command_name "freshness"
+
         option :prefix, "--prefix=KEY"
         option :zone, "--zone=Z"
 
         def call(store)
-          rows = operations_for(store).reads.freshness.call(prefix: prefix, zone: zone)
+          rows = operations_for(store).freshness(prefix: prefix, zone: zone)
           emit({ "verb" => "freshness", "rows" => rows })
         end
       end