textus 0.22.0 → 0.29.0

data/lib/textus/{application/writes/envelope_io.rb → envelope/io/writer.rb}

@@ -1,56 +1,38 @@
 require "fileutils"
 
 module Textus
-  module Application
-    module Writes
-      # Owns the write pipeline (validate, serialize, etag-check, write, audit)
-      # extracted from Store::Writer. Talks to ports (FileStore, Schemas,
-      # AuditLog, Manifest) instead of File/FileUtils and Store directly.
+  class Envelope
+    module IO
+      # Owns the write pipeline (validate, serialize, etag-check, write, audit).
+      # Talks to ports (FileStore, Schemas, AuditLog, Manifest) and an
+      # Reader for the existing-uid lookup.
+      #
+      # Invariant: every public method's final action is @audit_log.append(...).
       #
       # No permission check, no event firing — those belong to the caller
-      # (Application::Writes::Put / ::Delete / ::Mv).
-      class EnvelopeIO
+      # (Write::Put / ::Delete / ::Mv).
+      class Writer
         Payload = Data.define(:meta, :body, :content)
 
-        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:)
+        def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
           @file_store = file_store
           @manifest   = manifest
           @schemas    = schemas
           @audit_log  = audit_log
-          @ctx        = ctx
+          @call       = call
+          @reader     = reader
         end
 
-        def exists?(path) = @file_store.exists?(path)
-
-        # Reads an envelope by key, returning nil when absent. Used by Mv
-        # to inspect pre-move state (UID presence, content surfacing) so
-        # the move pipeline can consolidate I/O in one place.
-        def read_envelope(key)
-          res = @manifest.resolver.resolve(key)
-          path = res.path
-          return nil unless @file_store.exists?(path)
-
-          mentry = res.entry
-          raw = @file_store.read(path)
-          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-          Envelope.build(
-            key: key, mentry: mentry, path: path,
-            meta: parsed["_meta"], body: parsed["body"],
-            etag: Etag.for_bytes(raw), content: parsed["content"]
-          )
-        end
-
-        def write(key, mentry:, payload:, if_etag: nil)
+        def put(key, mentry:, payload:, if_etag: nil)
           path = @manifest.resolver.resolve(key).path
 
           meta = payload.meta || {}
-          strategy = Entry.for_format(mentry.format)
 
-          existing_uid = existing_uid_for(mentry, path)
+          existing_uid = @reader.existing_uid(key)
           meta, content = ensure_uid(mentry.format, meta, payload.content, existing_uid)
 
           bytes, eff_meta, eff_body, eff_content = serialize_for_put(
-            mentry: mentry, path: path, strategy: strategy,
+            mentry: mentry, path: path,
             meta: meta, body: payload.body, content: content
           )
 
@@ -69,19 +51,22 @@ module Textus
 
           @file_store.write(path, bytes)
           etag_after = Etag.for_bytes(bytes)
-          @audit_log.append(
-            role: @ctx.role, verb: "put", key: key,
-            etag_before: etag_before, etag_after: etag_after,
-            extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
-          )
-          Envelope.build(
+          envelope = Textus::Envelope.build(
             key: key, mentry: mentry, path: path,
             meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
           )
+          @audit_log.append(
+            role: @call.role, verb: "put", key: key,
+            etag_before: etag_before, etag_after: etag_after,
+            extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
+          )
+          envelope
         end
 
-        def delete(key, mentry:, if_etag: nil)
-          _ = mentry
+        def delete(key, mentry: nil, if_etag: nil) # rubocop:disable Lint/UnusedMethodArgument
+          # `mentry:` is accepted for symmetry with `put` / `move` and to
+          # leave room for future format-specific delete hooks; no field
+          # on it is needed today.
           path = @manifest.resolver.resolve(key).path
           raise UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)) unless @file_store.exists?(path)
 
@@ -90,9 +75,9 @@ module Textus
 
           @file_store.delete(path)
           @audit_log.append(
-            role: @ctx.role, verb: "delete", key: key,
+            role: @call.role, verb: "delete", key: key,
             etag_before: etag_before, etag_after: nil,
-            extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
+            extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
           )
         end
 
@@ -112,7 +97,7 @@ module Textus
 
           raw = @file_store.read(to_path)
           parsed = Entry.for_format(new_mentry.format).parse(raw, path: to_path)
-          envelope = Envelope.build(
+          envelope = Textus::Envelope.build(
             key: to_key, mentry: new_mentry, path: to_path,
             meta: parsed["_meta"], body: parsed["body"],
             etag: etag_after, content: parsed["content"]
@@ -123,10 +108,10 @@ module Textus
             "from_path" => from_path, "to_path" => to_path,
             "uid" => envelope.uid
           }
-          extras["correlation_id"] = @ctx.correlation_id if @ctx.correlation_id
+          extras["correlation_id"] = @call.correlation_id if @call.correlation_id
 
           @audit_log.append(
-            role: @ctx.role, verb: "mv", key: to_key,
+            role: @call.role, verb: "mv", key: to_key,
             etag_before: etag_before, etag_after: etag_after,
             extras: extras
           )
@@ -136,16 +121,6 @@ module Textus
 
         private
 
-        def existing_uid_for(mentry, path)
-          return nil unless @file_store.exists?(path)
-
-          raw = @file_store.read(path)
-          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-          Envelope.extract_uid(parsed["_meta"])
-        rescue StandardError
-          nil
-        end
-
         def ensure_uid(format, meta, content, existing_uid)
           Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
         end
@@ -154,8 +129,7 @@ module Textus
           Textus::Entry.for_format(format).enforce_name_match!(path, meta)
         end
 
-        def serialize_for_put(mentry:, path:, strategy:, meta:, body:, content:)
-          _ = strategy
+        def serialize_for_put(mentry:, path:, meta:, body:, content:)
           Textus::Entry.for_format(mentry.format).serialize_for_put(
             meta: meta, body: body, content: content, path: path,
           )

data/lib/textus/hooks/builtin.rb

@@ -7,23 +7,23 @@ module Textus
   module Hooks
     module Builtin
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      def self.register_all(bus)
-        bus.on(:resolve_intake, :json) do |store:, config:, args:|
-          _ = store
+      def self.register_all(events:, rpc:) # rubocop:disable Lint/UnusedMethodArgument
+        rpc.register(:resolve_intake, :json) do |caps:, config:, args:|
+          _ = caps
           _ = args
           data = JSON.parse(config["bytes"].to_s)
           { _meta: {}, body: YAML.dump(data) }
         end
 
-        bus.on(:resolve_intake, :csv) do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :csv) do |caps:, config:, args:|
+          _ = caps
           _ = args
           rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
           { _meta: {}, body: YAML.dump(rows) }
         end
 
-        bus.on(:resolve_intake, :"markdown-links") do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :"markdown-links") do |caps:, config:, args:|
+          _ = caps
           _ = args
           links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
             { "text" => text, "href" => href }
@@ -31,27 +31,27 @@ module Textus
           { _meta: {}, body: YAML.dump(links) }
         end
 
-        bus.on(:resolve_intake, :"ical-events") do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :"ical-events") do |caps:, config:, args:|
+          _ = caps
           _ = args
-          events = []
+          events_list = []
           current = nil
           config["bytes"].to_s.each_line do |line|
             line = line.strip
             case line
             when "BEGIN:VEVENT" then current = {}
             when "END:VEVENT"
-              events << current if current
+              events_list << current if current
               current = nil
             when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
               current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
             end
           end
-          { _meta: {}, body: YAML.dump(events) }
+          { _meta: {}, body: YAML.dump(events_list) }
         end
 
-        bus.on(:resolve_intake, :rss) do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :rss) do |caps:, config:, args:|
+          _ = caps
           _ = args
           doc = REXML::Document.new(config["bytes"].to_s)
           items = doc.elements.to_a("//item").map do |item|

data/lib/textus/hooks/context.rb

@@ -3,31 +3,48 @@
 module Textus
   module Hooks
     # A narrow handle passed to user hooks in place of the raw Store.
-    # All writes route back through Operations so authorization, audit
+    # All writes route back through the RoleScope so authorization, audit
     # logging, and schema validation always fire.
     class Context
       attr_reader :role, :correlation_id
 
-      def initialize(ops:)
-        @ops = ops
-        @role = ops.ctx.role
-        @correlation_id = ops.ctx.correlation_id
+      def self.for(container:, call:)
+        scope = Textus::RoleScope.new(
+          container: container,
+          role: call.role,
+          correlation_id: call.correlation_id,
+          dry_run: call.dry_run,
+        )
+        new(scope: scope)
+      end
+
+      def initialize(scope:)
+        @scope          = scope
+        @role           = scope.role
+        @correlation_id = scope.correlation_id
+      end
+
+      def backend
+        @scope
       end
 
       # read
-      def get(key)                = @ops.get(key)
-      def list(**)                = @ops.list(**)
-      def deps(key)               = @ops.deps(key)
-      def freshness(key)          = @ops.freshness(key)
+      def get(key)                = @scope.get(key)
+      def list(**)                = @scope.list(**)
+      def deps(key)               = @scope.deps(key)
+      def freshness(key)          = @scope.freshness(key)
 
       # write (authorized + audited)
-      def put(key, **)          = @ops.put(key, **)
-      def delete(key, **)       = @ops.delete(key, **)
-      def audit(verb, key:, **) = @ops.store.audit_log.append(role: @role, verb: verb, key: key, **)
+      def put(key, **)          = @scope.put(key, **)
+      def delete(key, **)       = @scope.delete(key, **)
+
+      def audit(verb, key:, **)
+        @scope.container.audit_log.append(role: @role, verb: verb, key: key, **)
+      end
 
       # fan-out
       def publish_followup(event, **)
-        @ops.store.bus.publish(event, ctx: self, **)
+        @scope.container.events.publish(event, ctx: self, **)
       end
 
       def inspect

data/lib/textus/hooks/error_log.rb

@@ -0,0 +1,32 @@
+module Textus
+  module Hooks
+    # Bounded in-memory ring buffer of recent hook failures (errored and
+    # timed_out). Each row carries the audit `seq` observed at the time of
+    # failure so pulse can filter "errors since cursor".
+    class ErrorLog
+      DEFAULT_CAPACITY = 256
+
+      def initialize(capacity: DEFAULT_CAPACITY)
+        @capacity = capacity
+        @rows = []
+        @mutex = Mutex.new
+      end
+
+      def record(seq:, event:, hook:, key:, error_class:, error_message:)
+        row = {
+          seq: seq, event: event, hook: hook, key: key,
+          error_class: error_class, error_message: error_message,
+          at: Time.now.utc.iso8601
+        }
+        @mutex.synchronize do
+          @rows << row
+          @rows.shift while @rows.size > @capacity
+        end
+      end
+
+      def since(seq)
+        @mutex.synchronize { @rows.select { |r| r[:seq] > seq }.dup }
+      end
+    end
+  end
+end

data/lib/textus/hooks/{bus.rb → event_bus.rb}

@@ -2,67 +2,55 @@
 
 module Textus
   module Hooks
-    class Bus
+    class EventBus
       HOOK_TIMEOUT_SECONDS = 2
 
       class HookTimeout < StandardError; end
 
       EVENTS = {
-        # RPC events — gem-internal, keep :store
-        resolve_intake: { mode: :rpc, args: %i[store config args] },
-        transform_rows: { mode: :rpc, args: %i[store rows config] },
-        validate: { mode: :rpc, args: %i[store] },
-
-        # Pubsub events — ship :ctx (Hooks::Context) instead of raw store
-        entry_put: { mode: :pubsub, args: %i[ctx key envelope] },
-        entry_deleted: { mode: :pubsub, args: %i[ctx key] },
-        entry_refreshed: { mode: :pubsub, args: %i[ctx key envelope change] },
-        entry_renamed: { mode: :pubsub, args: %i[ctx key from_key to_key envelope] },
-        build_completed: { mode: :pubsub, args: %i[ctx key envelope sources] },
-        proposal_accepted: { mode: :pubsub, args: %i[ctx key target_key] },
-        proposal_rejected: { mode: :pubsub, args: %i[ctx key target_key] },
-        file_published: { mode: :pubsub, args: %i[ctx key envelope source target] },
-        store_loaded: { mode: :pubsub, args: %i[ctx] },
-        refresh_started: { mode: :pubsub, args: %i[ctx key mode] },
-        refresh_failed: { mode: :pubsub, args: %i[ctx key error_class error_message] },
-        refresh_backgrounded: { mode: :pubsub, args: %i[ctx key started_at budget_ms] },
+        entry_put: %i[ctx key envelope],
+        entry_deleted: %i[ctx key],
+        entry_refreshed: %i[ctx key envelope change],
+        entry_renamed: %i[ctx key from_key to_key envelope],
+        build_completed: %i[ctx key envelope sources],
+        proposal_accepted: %i[ctx key target_key],
+        proposal_rejected: %i[ctx key target_key],
+        file_published: %i[ctx key envelope source target],
+        store_loaded: %i[ctx],
+        refresh_started: %i[ctx key mode],
+        refresh_failed: %i[ctx key error_class error_message],
+        refresh_backgrounded: %i[ctx key started_at budget_ms],
       }.freeze
 
-      def initialize
-        @rpc    = Hash.new { |h, k| h[k] = {} }
+      RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze
+
+      def initialize(error_log: ErrorLog.new)
         @pubsub = Hash.new { |h, k| h[k] = [] }
         @error_handlers = []
+        @error_log = error_log
       end
 
+      attr_reader :error_log
+
       def on(event, name, keys: nil, &) = register(event, name, keys: keys, &)
 
       def register(event, name, keys: nil, &blk)
         event_sym = event.to_sym
-        spec = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
-        shape_check!(event_sym, spec, blk)
-        name = name.to_sym
-
-        case spec[:mode]
-        when :rpc
-          raise UsageError.new("#{event_sym} '#{name}' already registered") if @rpc[event_sym].key?(name)
+        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
 
-          @rpc[event_sym][name] = blk
-        when :pubsub
-          raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
+        required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
+        shape_check!(event_sym, required, blk)
+        name = name.to_sym
+        raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
 
-          @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
-        end
+        @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
       end
 
       def on_error(&block) = @error_handlers << block
 
-      def rpc_callable(event, name)
-        @rpc[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
-      end
+      def listeners(event, key:) = @pubsub[event.to_sym].select { |h| match?(h[:keys], key) }
 
-      def rpc_names(event)        = @rpc[event.to_sym].keys
-      def pubsub_handlers(event)  = @pubsub[event.to_sym]
-      def listeners(event, key:)  = @pubsub[event.to_sym].select { |h| h[:keys].nil? || matches_any?(h[:keys], key) }
+      def pubsub_handlers(event) = @pubsub[event.to_sym]
 
       def publish(event, strict: false, **kwargs)
         key = kwargs[:key] || "-"
@@ -93,29 +81,33 @@ module Textus
       def invoke(event, sub, key, kwargs)
         accepted = filter_kwargs(sub[:callable], kwargs)
         error = nil
-
         thread = Thread.new do
           sub[:callable].call(**accepted)
         rescue StandardError => e
           error = e
         end
-
         if thread.join(HOOK_TIMEOUT_SECONDS).nil?
           thread.kill
           err = HookTimeout.new("hook #{sub[:name]} exceeded #{HOOK_TIMEOUT_SECONDS}s on event #{event}")
           notify_error(event, sub, key, kwargs, err)
           return [:timed_out, err]
         end
-
         if error
           notify_error(event, sub, key, kwargs, error)
           return [:errored, error]
         end
-
         [:ok, nil]
       end
 
       def notify_error(event, sub, key, kwargs, error)
+        @error_log.record(
+          seq: kwargs[:_audit_seq] || -1,
+          event: event,
+          hook: sub[:name],
+          key: key,
+          error_class: error.class.name,
+          error_message: error.message,
+        )
         @error_handlers.each do |handler|
           handler.call(event: event, hook: sub[:name], key: key, kwargs: kwargs, error: error)
         rescue StandardError => e
@@ -127,18 +119,16 @@ module Textus
         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
+        accepted = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
         kwargs.slice(*accepted)
       end
 
-      def shape_check!(event, spec, blk)
-        required = spec[:args]
+      def shape_check!(event, required, blk)
         provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        keyrest  = provided.any? { |t, _| t == :keyrest }
-        missing  = required - provided.map { |_, n| n }
-        return if keyrest || missing.empty?
+        return if provided.any? { |t, _| t == :keyrest }
+
+        missing = required - provided.map { |_, n| n }
+        return if missing.empty?
 
         raise UsageError.new("#{event} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
       end
@@ -148,8 +138,6 @@ module Textus
 
         Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
       end
-
-      def matches_any?(globs, key) = match?(globs, key)
     end
   end
 end

data/lib/textus/hooks/loader.rb

@@ -1,8 +1,34 @@
 module Textus
   module Hooks
     class Loader
-      def initialize(bus:)
-        @bus = bus
+      # A small DSL object passed to user hook blocks. Routes `.on(...)` to the
+      # EventBus and `.rpc(...)` / `.register(...)` to the RpcRegistry.
+      class Dsl
+        def initialize(events:, rpc:)
+          @events = events
+          @rpc    = rpc
+        end
+
+        # Pubsub registration — delegates to EventBus.
+        # Also handles RPC event names by delegating to RpcRegistry.
+        def on(event, name, keys: nil, &)
+          if Hooks::RpcRegistry::EVENTS.key?(event.to_sym)
+            @rpc.register(event, name, &)
+          else
+            @events.register(event, name, keys: keys, &)
+          end
+        end
+
+        # Explicit RPC registration.
+        def register(event, name, &)
+          @rpc.register(event, name, &)
+        end
+      end
+
+      def initialize(events:, rpc:)
+        @events = events
+        @rpc    = rpc
+        @dsl    = Dsl.new(events: @events, rpc: @rpc)
       end
 
       def load_dir(dir)
@@ -18,7 +44,7 @@ module Textus
         end
 
         Textus.drain_hook_blocks.each do |blk|
-          blk.call(@bus)
+          blk.call(@dsl)
         rescue StandardError, ScriptError => e
           raise UsageError.new("failed registering hook: #{e.class}: #{e.message}")
         end

data/lib/textus/hooks/rpc_registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    class RpcRegistry
+      EVENTS = {
+        resolve_intake: %i[caps config args],
+        transform_rows: %i[caps rows config],
+        validate: %i[caps],
+      }.freeze
+
+      PUBSUB_EVENTS = EventBus::EVENTS.keys.freeze
+
+      def initialize
+        @table = Hash.new { |h, k| h[k] = {} }
+      end
+
+      def register(event, name, &blk)
+        event_sym = event.to_sym
+        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
+
+        required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
+        shape_check!(event_sym, required, blk)
+        name = name.to_sym
+        raise UsageError.new("#{event_sym} '#{name}' already registered") if @table[event_sym].key?(name)
+
+        @table[event_sym][name] = blk
+      end
+
+      def names(event) = @table[event.to_sym].keys
+
+      def callable(event, name)
+        @table[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
+      end
+
+      # Invoke a registered callable, injecting `caps:` under the kwarg name
+      # the callable declares. Legacy `store:` is rejected (no shim).
+      def invoke(event, name, caps:, **other)
+        blk = callable(event, name)
+        params = blk.parameters
+        accepts_keyrest = params.any? { |t, _| t == :keyrest }
+        declared = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
+
+        if declared.include?(:store)
+          raise UsageError.new(
+            "RPC callable for #{event} '#{name}' declares legacy `store:`; rename to `caps:` " \
+            "(Textus::Container)",
+          )
+        end
+
+        kwargs = other.dup
+        kwargs[:caps] = caps if accepts_keyrest || declared.include?(:caps)
+        blk.call(**kwargs)
+      end
+
+      private
+
+      def shape_check!(event, required, blk)
+        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
+        return if provided.any? { |t, _| t == :keyrest }
+
+        param_names = provided.map { |_, n| n }
+        # Allow `store:` as a stand-in for `caps:` so registration succeeds;
+        # invoke will raise UsageError when the callable is actually called.
+        effective_required = if param_names.include?(:store)
+                               required.map { |r| r == :caps ? :store : r }
+                             else
+                               required
+                             end
+        missing = effective_required - param_names
+        return if missing.empty?
+
+        raise UsageError.new("#{event} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
+      end
+    end
+  end
+end

data/lib/textus/key/path.rb

@@ -4,12 +4,16 @@ module Textus
       # Returns the absolute filesystem path for a manifest entry (the leaf file,
       # not a nested directory). Adds the format's primary extension when the
       # manifest entry's `path:` is extensionless.
-      def self.resolve(manifest, mentry)
+      #
+      # The first argument is a Manifest::Data (or anything responding to .root);
+      # callers historically passed the whole Manifest but should now pass
+      # `manifest.data`.
+      def self.resolve(data, mentry)
         primary_ext = Entry.for_format(mentry.format).extensions.first
         if File.extname(mentry.path) == ""
-          File.join(manifest.root, "zones", mentry.path + primary_ext)
+          File.join(data.root, "zones", mentry.path + primary_ext)
         else
-          File.join(manifest.root, "zones", mentry.path)
+          File.join(data.root, "zones", mentry.path)
         end
       end
     end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -0,0 +1,36 @@
+module Textus
+  module Maintenance
+    # Bulk-delete every leaf key under `prefix`.
+    class KeyDeletePrefix
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+      end
+
+      def call(prefix:, dry_run: false)
+        raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
+
+        leaves = Read::List.new(container: @container)
+                           .call(prefix: prefix)
+                           .map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+
+        warnings = leaves.empty? ? ["no keys under #{prefix}"] : []
+        steps = leaves.map { |k| { "op" => "delete", "key" => k } }
+
+        plan = Plan.new(steps: steps, warnings: warnings)
+        return plan if dry_run
+
+        steps.each do |s|
+          delete.call(s["key"])
+        end
+        plan
+      end
+
+      private
+
+      def delete
+        Write::Delete.new(container: @container, call: @call)
+      end
+    end
+  end
+end