textus 0.52.0 → 0.53.0

data/lib/textus/action/data_mv.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Textus
+  module Action
+    class DataMv < Base
+      extend Textus::Contract::DSL
+
+      verb :data_mv
+      summary "Rename a data lane — manifest + files. Refuses if destination exists."
+      surfaces :cli, :mcp
+      cli "data mv"
+      arg :from, String, required: true, positional: true, description: "current data lane name"
+      arg :to, String, required: true, positional: true,
+                       description: "new data lane name; refused if a lane by this name already exists"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the planned zone move without applying it; " \
+                                           "defaults to false, so omitting it applies the move immediately"
+      view { |v, _i| v.to_h }
+
+      BURN = :sync
+
+      def initialize(from:, to:, dry_run: false)
+        super()
+        @from = from
+        @to = to
+        @dry_run = dry_run
+      end
+
+      def call(container:, **)
+        manifest = container.manifest
+        root = container.root
+
+        raise UsageError.new("from and to required") if @from.nil? || @to.nil? || @from.empty? || @to.empty?
+        raise UsageError.new("data lane '#{@from}' not declared") unless manifest.data.declared_lane_kinds.key?(@from)
+
+        dest_dir = File.join(root, "data", @to)
+        raise UsageError.new("destination 'data/#{@to}' already exists") if File.exist?(dest_dir)
+
+        affected_keys = manifest.data.entries.select { |entry| entry.lane == @from }.map(&:key)
+
+        steps = [{ "op" => "rename_zone", "from" => @from, "to" => @to }]
+        steps += affected_keys.map do |key|
+          { "op" => "mv", "from" => key, "to" => "#{@to}#{key[@from.length..]}" }
+        end
+
+        plan = Textus::Background::Plan.new(steps: steps, warnings: [])
+        return plan if @dry_run
+
+        rewrite_manifest!(root)
+        FileUtils.mv(File.join(root, "data", @from), dest_dir)
+        plan
+      end
+
+      private
+
+      def rewrite_manifest!(root)
+        path = File.join(root, "manifest.yaml")
+        raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+        raw["lanes"].each { |lane| lane["name"] = @to if lane["name"] == @from }
+        raw["entries"].each do |entry|
+          entry["lane"] = @to if entry["lane"] == @from
+          entry["key"] = entry["key"].sub(/\A#{Regexp.escape(@from)}(\.|\z)/, "#{@to}\\1")
+          entry["path"] = entry["path"].sub(%r{\A(data/)?#{Regexp.escape(@from)}(/|\z)}, "\\1#{@to}\\2")
+        end
+        File.write(path, YAML.dump(raw))
+      end
+    end
+  end
+end

data/lib/textus/action/deps.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Deps < Base
+      extend Textus::Contract::DSL
+
+      verb :deps
+      summary "List the keys a derived entry depends on (its projection/external sources)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key of the derived entry whose source keys you want"
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        entry = container.manifest.data.entries.find { |e| e.key == @key }
+        deps =
+          if entry&.derived?
+            src = entry.source
+            if src.projection?
+              Array(src.select).compact
+            elsif src.external?
+              Array(src.sources).compact
+            else
+              []
+            end
+          else
+            []
+          end
+        { "key" => @key, "deps" => deps.uniq }
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/doctor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Doctor < Base
+      extend Textus::Contract::DSL
+
+      verb :doctor
+      summary "Run health checks on the textus store and report any issues."
+      surfaces :cli
+      cli "doctor"
+      arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
+
+      BURN = :sync
+
+      def initialize(checks: nil)
+        super()
+        @checks = checks
+      end
+
+      def call(container:, call:, **)
+        Textus::Doctor.build(container: container, checks: @checks, role: call.role)
+      end
+    end
+  end
+end

data/lib/textus/action/drain.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Drain < Base
+      extend Textus::Contract::DSL
+
+      verb :drain
+      summary "Seed refresh + sweep jobs then drain the queue to empty. " \
+              "Identical to one Watcher tick. Use when no watcher is running."
+      surfaces :cli, :mcp
+      arg :prefix, String, description: "restrict to keys under this dotted prefix"
+      arg :lane,   String, description: "restrict to entries in this lane"
+
+      BURN = :sync
+
+      def initialize(prefix: nil, lane: nil)
+        super()
+        @prefix = prefix
+        @lane   = lane
+      end
+
+      def call(container:, call:)
+        queue = Textus::Ports::Queue.new(root: container.root)
+        Textus::Background::Planner::Plan.seed(
+          container: container,
+          queue: queue,
+          role: call.role,
+        )
+        queue.reclaim(now: Textus::Ports::Clock.new.now)
+        summary = Textus::Background::Worker.for(container:, queue:).drain
+        {
+          "protocol" => Textus::PROTOCOL,
+          "ok" => summary.failed.zero?,
+          "completed" => summary.completed,
+          "failed" => summary.failed,
+        }
+      end
+    end
+  end
+end

data/lib/textus/action/enqueue.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Enqueue < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :enqueue
+      summary "Push a registered job type onto the convergence queue, to be run by drain/serve."
+      surfaces :cli, :mcp
+      cli "enqueue"
+      arg :type, String, required: true, positional: true,
+                         description: "registered job type (e.g. materialize, re-pull, sweep)"
+      arg :args, Hash, default: {},
+                       description: "type-specific arguments (e.g. { key: ... } or { scope: ... })"
+
+      BURN = :sync
+
+      def initialize(type:, args: {})
+        super()
+        @type = type
+        @job_args = args
+      end
+
+      def args
+        { type: @type, args: @job_args }
+      end
+
+      def call(container:, call:)
+        action_class = begin
+          Textus::Background::Job.fetch(@type.to_s)
+        rescue Textus::UsageError
+          raise Textus::UsageError.new("unregistered job type '#{@type}'")
+        end
+        if action_class.const_defined?(:REQUIRED_ROLE) && call.role != action_class::REQUIRED_ROLE
+          raise Textus::Error.new(
+            "forbidden",
+            "role '#{call.role}' is not authorized to enqueue this job type (requires '#{action_class::REQUIRED_ROLE}')",
+            details: { "role" => call.role, "required_role" => action_class::REQUIRED_ROLE },
+            exit_code: 77,
+          )
+        end
+
+        job = Textus::Ports::Queue::Job.new(
+          type: @type,
+          args: @job_args,
+          enqueued_by: call.role,
+          max_attempts: 3,
+        )
+        Textus::Ports::Queue.new(root: container.root).enqueue(job)
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id }
+      end
+    end
+  end
+end

data/lib/textus/action/get.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Get < Base
+      extend Textus::Contract::DSL
+
+      verb :get
+      summary "Read one entry - a pure on-disk read annotated with a freshness " \
+              "verdict; never ingests (quarantine freshness is drain + hook " \
+              "only, ADR 0089). Returns the envelope (uid, etag, _meta, body, " \
+              "freshness)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key to read, e.g. 'knowledge.project'"
+      view { |v, _i| v.to_h_for_wire }
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call:, file_stat: Textus::Ports::Storage::FileStat.new)
+        @container = container
+        @call = call
+        @manifest = container.manifest
+        @file_store = container.file_store
+        @file_stat = file_stat
+        annotated_envelope(@key)
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+
+      private
+
+      def annotated_envelope(key)
+        envelope = read_raw_envelope(key)
+        return nil if envelope.nil?
+
+        entry = @manifest.resolver.resolve(key).entry
+        envelope.with(freshness: evaluator.verdict(entry))
+      end
+
+      def evaluator
+        @evaluator ||= Textus::Core::Freshness::Evaluator.new(
+          manifest: @manifest,
+          file_stat: @file_stat,
+          clock: @call,
+        )
+      end
+
+      def read_raw_envelope(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        return nil unless @file_store.exists?(path)
+
+        raw = @file_store.read(path)
+        parsed = Textus::Entry.for_format(mentry.format).parse(raw, path: path)
+        Textus::Envelope.build(
+          key: key,
+          mentry: mentry,
+          path: path,
+          meta: parsed["_meta"],
+          body: parsed["body"],
+          etag: Textus::Etag.for_bytes(raw),
+          content: parsed["content"],
+        )
+      end
+    end
+  end
+end

data/lib/textus/action/jobs.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Jobs < Base
+      extend Textus::Contract::DSL
+
+      verb :jobs
+      summary "List queued jobs by state; retry a dead-lettered job or purge a state."
+      surfaces :cli, :mcp
+      cli "jobs"
+      arg :state, String, default: "ready", description: "ready|leased|done|failed"
+      arg :action, String, default: nil, description: "retry|purge (optional)"
+      arg :job_id, String, default: nil, description: "job id (required for action=retry)"
+
+      BURN = :sync
+
+      def initialize(state: "ready", action: nil, job_id: nil)
+        super()
+        @state = state
+        @action = action
+        @job_id = job_id
+      end
+
+      def call(container:, **)
+        queue = Textus::Ports::Queue.new(root: container.root)
+        case @action
+        when "retry"
+          queue.retry_failed(@job_id)
+        when "purge"
+          queue.purge(@state)
+        end
+
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "state" => @state, "jobs" => queue.list(@state) }
+      end
+    end
+  end
+end

data/lib/textus/action/key_delete.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class KeyDelete < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :key_delete
+      summary "Delete one entry by key. Single-key, lower blast radius than key_delete_prefix; " \
+              "guarded by an optional optimistic-concurrency etag. Returns {ok, key, deleted}."
+      surfaces :cli, :mcp
+      cli "key delete"
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key to delete"
+      arg :if_etag, String,
+          description: "optimistic-concurrency guard: the etag you last read; the delete is rejected if the entry changed since"
+
+      BURN = :sync
+
+      def initialize(key:, if_etag: nil)
+        super()
+        @key = key
+        @if_etag = if_etag
+      end
+
+      def call(container:, call:)
+        run_with_cascade(@key, container:, call:) do
+          Textus::Manifest::Data.validate_key!(@key)
+          mentry = container.manifest.resolver.resolve(@key).entry
+
+          auth(container).check_action!(action: :key_delete, actor: call.role, key: @key, extra: { if_etag: @if_etag })
+
+          writer(container, call).delete(@key, mentry:, if_etag: @if_etag)
+
+          container.steps.publish(
+            :entry_deleted,
+            ctx: Textus::Step::Context.for(container: container, call: call),
+            key: @key,
+          )
+
+          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => @key, "deleted" => true }
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/key_delete_prefix.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class KeyDeletePrefix < Base
+      extend Textus::Contract::DSL
+
+      verb :key_delete_prefix
+      summary "Bulk-delete every leaf key under prefix."
+      surfaces :cli, :mcp
+      cli "key delete-prefix"
+      arg :prefix, String, required: true, positional: true,
+                           description: "every leaf key under this dotted prefix is deleted"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the keys that would be deleted without deleting them; " \
+                                           "defaults to false, so omitting it deletes immediately"
+      view { |v, _i| v.to_h }
+
+      BURN = :sync
+
+      def initialize(prefix:, dry_run: false)
+        super()
+        @prefix = prefix
+        @dry_run = dry_run
+      end
+
+      def call(container:, call:)
+        raise UsageError.new("prefix required") if @prefix.nil? || @prefix.empty?
+
+        leaves = Textus::Action::List.new(prefix: @prefix).call(container: container)
+                                     .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+
+        warnings = leaves.empty? ? ["no keys under #{@prefix}"] : []
+        steps = leaves.map { |key| { "op" => "delete", "key" => key } }
+
+        plan = Textus::Background::Plan.new(steps: steps, warnings: warnings)
+        return plan if @dry_run
+
+        steps.each do |step|
+          Textus::Action::KeyDelete.new(key: step["key"]).call(container: container, call: call)
+        end
+        plan
+      end
+    end
+  end
+end

data/lib/textus/action/key_mv.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class KeyMv < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :key_mv
+      summary "Rename one entry (same zone + format). Refuses if the target exists. Single-key, lower blast radius than key_mv_prefix."
+      surfaces :cli, :mcp
+      cli "key mv"
+      arg :old_key, String, required: true, positional: true,
+                            description: "current dotted key"
+      arg :new_key, String, required: true, positional: true,
+                            description: "new dotted key (must be the same zone and format as old_key)"
+      arg :dry_run, :boolean,
+          description: "when true, returns the planned move (from/to paths, uid) without applying it; " \
+                       "defaults to false, so omitting it applies the move immediately " \
+                       "(unlike the bulk key_mv_prefix, which defaults to a dry-run plan)"
+
+      BURN = :sync
+
+      def initialize(old_key:, new_key:, dry_run: false)
+        super()
+        @old_key = old_key
+        @new_key = new_key
+        @dry_run = dry_run
+      end
+
+      def call(container:, call:)
+        run_with_cascade(cascade_target_key, container:, call:) do
+          execute_move(container, call)
+        end
+      end
+
+      private
+
+      def cascade_target_key
+        @dry_run ? nil : @new_key
+      end
+
+      def execute_move(container, call)
+        old_res, new_res = prepare(container, call)
+        return dry_run_result(container, old_res, new_res) if @dry_run
+
+        envelope = apply_move(container, call, old_res, new_res)
+        publish_rename(container, call, envelope)
+        success_result(old_res, new_res, envelope)
+      end
+
+      def apply_move(container, call, old_res, new_res)
+        ensure_uid!(container, call, old_res.entry)
+        writer(container, call).move(
+          from_key: @old_key,
+          to_key: @new_key,
+          new_mentry: new_res.entry,
+        )
+      end
+
+      def publish_rename(container, call, envelope)
+        container.steps.publish(
+          :entry_renamed,
+          ctx: Textus::Step::Context.for(container: container, call: call),
+          key: @new_key,
+          from_key: @old_key,
+          to_key: @new_key,
+          envelope: envelope,
+        )
+      end
+
+      def success_result(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
+
+      def prepare(container, call)
+        Textus::Manifest::Data.validate_key!(@old_key)
+        Textus::Manifest::Data.validate_key!(@new_key)
+        raise UsageError.new("mv: old and new keys are identical") if @old_key == @new_key
+
+        old_res = container.manifest.resolver.resolve(@old_key)
+        new_res = container.manifest.resolver.resolve(@new_key)
+        raise UnknownKey.new(@old_key) unless reader(container).exists?(@old_key)
+
+        validate_zone_and_format!(old_res.entry, new_res.entry)
+        auth(container).check_action!(action: :key_mv, actor: call.role, key: @old_key)
+        auth(container).check_action!(action: :key_mv, actor: call.role, key: @new_key)
+        raise UsageError.new("mv: target '#{@new_key}' already exists at #{new_res.path}") if reader(container).exists?(@new_key)
+
+        [old_res, new_res]
+      end
+
+      def validate_zone_and_format!(old_mentry, new_mentry)
+        if old_mentry.lane != new_mentry.lane
+          raise UsageError.new(
+            "mv: cross-zone move refused (#{old_mentry.lane} -> #{new_mentry.lane}). " \
+            "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
+
+      def ensure_uid!(container, call, old_mentry)
+        pre_env = reader(container).read(@old_key)
+        return if pre_env.uid
+
+        writer(container, call).put(
+          @old_key,
+          mentry: old_mentry,
+          payload: Textus::Envelope::IO::Writer::Payload.new(
+            meta: pre_env.meta,
+            body: pre_env.body,
+            content: pre_env.content,
+          ),
+        )
+      end
+
+      def dry_run_result(container, old_res, new_res)
+        pre_env = reader(container).read(@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
+    end
+  end
+end

data/lib/textus/action/key_mv_prefix.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class KeyMvPrefix < Base
+      extend Textus::Contract::DSL
+
+      verb :key_mv_prefix
+      summary "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
+      surfaces :cli, :mcp
+      cli "key mv-prefix"
+      arg :from_prefix, String, required: true, positional: true,
+                                description: "dotted prefix whose leaf keys are renamed"
+      arg :to_prefix, String, required: true, positional: true,
+                              description: "dotted prefix the keys are renamed to"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the planned moves without applying them; defaults " \
+                                           "to false, so omitting it applies the rename immediately"
+      view { |v, _i| v.to_h }
+
+      BURN = :sync
+
+      def initialize(from_prefix:, to_prefix:, dry_run: false)
+        super()
+        @from_prefix = from_prefix
+        @to_prefix = to_prefix
+        @dry_run = dry_run
+      end
+
+      def call(container:, call:)
+        raise UsageError.new("from_prefix and to_prefix required") if @from_prefix.nil? || @to_prefix.nil?
+
+        leaves = Textus::Action::List.new(prefix: @from_prefix).call(container: container)
+                                     .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+
+        if leaves.include?(@from_prefix)
+          raise UsageError.new("from_prefix '#{@from_prefix}' is itself a leaf — use `mv` to rename a single key")
+        end
+
+        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 = Textus::Background::Plan.new(steps: steps, warnings: warnings)
+        return plan if @dry_run
+
+        steps.each do |step|
+          Textus::Action::KeyMv.new(old_key: step["from"], new_key: step["to"]).call(container: container, call: call)
+        end
+        plan
+      end
+    end
+  end
+end