textus 0.52.0 → 0.54.0

data/lib/textus/action/key_delete_prefix.rb

@@ -0,0 +1,44 @@
+# 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 }
+
+      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::Jobs::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,129 @@
+# 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)"
+
+      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)
+        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 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::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,57 @@
+# 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 }
+
+      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::Jobs::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

data/lib/textus/action/list.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class List < Base
+      extend Textus::Contract::DSL
+
+      verb :list
+      summary "List keys filtered by lane and/or prefix."
+      surfaces :cli, :mcp
+      arg :prefix, String,
+          description: "restrict to keys starting with this dotted prefix, e.g. 'knowledge.runbooks'"
+      arg :lane, String,
+          description: "restrict to one lane by name (see `boot` lanes); combine with prefix to narrow further"
+      view(:cli) { |rows| { "entries" => rows } }
+
+      def initialize(prefix: nil, lane: nil)
+        super()
+        @prefix = prefix
+        @lane = lane
+      end
+
+      def call(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        manifest = container.manifest
+        rows = manifest.resolver.enumerate(prefix: @prefix)
+        rows = rows.select { |row| row[:manifest_entry].lane == @lane } if @lane
+        rows.map { |row| { "key" => row[:key], "lane" => row[:manifest_entry].lane, "path" => row[:path] } }
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        call_spec = instance_method(:initialize).parameters
+        required = call_spec.slice(:keyreq).map(&:last)
+        optional = call_spec.slice(:key).map(&:last)
+        positional = required + optional
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/propose.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Propose < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :propose
+      summary "Write a proposal to the role's propose_lane. Auto-prefixes the key."
+      surfaces :cli, :mcp
+      cli_stdin :json
+      arg :key, String, required: true, positional: true,
+                        description: "key relative to propose_lane, e.g. 'decisions.feature-x'"
+      arg :meta, Hash, required: false, wire_name: :_meta,
+                       description: "frontmatter; reads back as `_meta` from `get`. Include a 'proposal:' block naming the target_key"
+      arg :body, String,
+          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
+      arg :content, Hash,
+          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
+      view { |env, _i| env.to_h_for_wire }
+
+      def initialize(key:, meta: nil, body: nil, content: nil)
+        super()
+        @key = key
+        @meta = meta
+        @body = body
+        @content = content
+      end
+
+      def call(container:, call:)
+        zone = container.manifest.policy.propose_lane_for(call.role)
+        unless zone
+          raise Textus::Error.new(
+            "propose_forbidden",
+            "role '#{call.role}' has no writable propose_lane",
+            details: { "role" => call.role },
+            hint: "the manifest must define a queue zone and '#{call.role}' must hold the 'propose' capability",
+          )
+        end
+
+        run_with_cascade("#{zone}.#{@key}", container:, call:) do
+          Textus::Action::Put.new(
+            key: "#{zone}.#{@key}",
+            meta: @meta || {},
+            body: @body,
+            content: @content,
+          ).call(container: container, call: call)
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/published.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Published < Base
+      extend Textus::Contract::DSL
+
+      verb :published
+      summary "List all entries that declare a publish_to target."
+      surfaces :cli
+      cli "published"
+
+      def args
+        {}
+      end
+
+      def call(container:, **)
+        container.manifest.data.entries.reject { |entry| entry.publish_to.empty? }.map do |entry|
+          { "key" => entry.key, "publish_to" => entry.publish_to }
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/pulse.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Textus
+  module Action
+    class Pulse < Base
+      extend Textus::Contract::DSL
+
+      verb :pulse
+      summary "Delta since cursor — changed entries, pending proposals, index freshness."
+      surfaces :cli, :mcp
+      around :cursor
+      arg :since, Integer, session_default: :cursor,
+                           description: "audit seq to diff from; defaults to the session cursor"
+
+      def initialize(since: nil)
+        super()
+        @since = since
+      end
+
+      def call(container:, call:)
+        @container = container
+        @call = call
+        @manifest = container.manifest
+        @audit_log = container.audit_log
+        @root = container.root
+
+        {
+          "cursor" => @audit_log.latest_seq,
+          "changed" => Textus::Action::Audit.new(seq_since: @since).call(container: container),
+          "pending_review" => review_keys,
+          "contract_etag" => Textus::Etag.for_contract(@root),
+          "index_etag" => index_etag(container),
+        }
+      end
+
+      private
+
+      def review_keys
+        queue = @manifest.policy.queue_lane
+        return [] unless queue
+
+        rows = Textus::Action::List.new(lane: queue).call(container: @container)
+        rows.map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+      end
+
+      def index_etag(container)
+        path = container.manifest.resolver.resolve("artifacts.index").path
+        File.exist?(path) ? container.file_store.etag(path) : nil
+      rescue Textus::Error
+        nil
+      end
+    end
+  end
+end

data/lib/textus/action/put.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Put < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :put
+      summary "Create or update an entry. Schema-validated. Returns {uid, etag}."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key, e.g. 'knowledge.project'; must resolve to a zone the role may write"
+      arg :meta, Hash, required: false, wire_name: :_meta,
+                       description: "frontmatter; reads back as `_meta` from `get`. Schema-validated — call `schema KEY` first"
+      arg :body, String,
+          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
+      arg :content, Hash,
+          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
+      arg :if_etag, String,
+          description: "optimistic-concurrency guard: the etag you last read; the write is rejected if the entry changed since"
+      view { |env| { "uid" => env.uid, "etag" => env.etag } }
+
+      def initialize(key:, meta: nil, body: nil, content: nil, if_etag: nil)
+        super()
+        @key = key
+        @meta = meta
+        @body = body
+        @content = content
+        @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
+          envelope = writer(container, call).put(
+            @key,
+            mentry: mentry,
+            payload: Textus::Envelope::Writer::Payload.new(
+              meta: @meta,
+              body: @body,
+              content: @content,
+            ),
+            if_etag: @if_etag,
+          )
+
+          envelope
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/rdeps.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Rdeps < Base
+      extend Textus::Contract::DSL
+
+      verb :rdeps
+      summary "List the derived entries that depend on a key (reverse deps / impact set)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key whose dependents (what would be stranded if it moved) you want"
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        manifest = container.manifest
+        rdeps = manifest.data.entries.each_with_object([]) do |entry, acc|
+          next unless entry.external?
+
+          sources = Array(entry.source&.sources).compact
+          acc << entry.key if sources.any? { |source| source == @key || @key.start_with?("#{source}.") }
+        end
+        { "key" => @key, "rdeps" => rdeps }
+      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/reject.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Reject < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :reject
+      summary "discard a queued proposal without applying it"
+      surfaces :cli, :mcp
+      cli "reject"
+      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
+
+      def initialize(pending_key:)
+        super()
+        @pending_key = pending_key
+      end
+
+      def call(container:, call:)
+        run_with_cascade(@pending_key, container:, call:) do
+          mentry = container.manifest.resolver.resolve(@pending_key).entry
+          unless mentry.in_proposal_lane?(container.manifest.policy)
+            raise ProposalError.new("reject: '#{@pending_key}' is not in a proposal zone (zone=#{mentry.lane})")
+          end
+
+          env = Textus::Action::Get.new(key: @pending_key).call(container: container, call: call)
+          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")
+
+          writer(container, call).delete(@pending_key, mentry: mentry)
+
+          { "protocol" => PROTOCOL, "rejected" => @pending_key, "target_key" => target_key }
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/rule_explain.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class RuleExplain < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_explain
+      summary "Effective rules for a key. Lean {lifecycle, guard} by default; detail: true adds matched blocks + guard predicates."
+      surfaces :cli, :mcp
+      cli "rule explain"
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key whose effective rules you want (lifecycle ttl/action, write guard, ...)"
+      arg :detail, :boolean,
+          description: "defaults false: lean {lifecycle, guard}. detail: true adds matched blocks + guard predicates per transition."
+      view(:cli) { |r| { "verb" => "rule_explain" }.merge(r.transform_keys(&:to_s)) }
+
+      def initialize(key:, detail: nil)
+        super()
+        @key = key
+        @detail = detail
+      end
+
+      def call(container:, **)
+        @manifest = container.manifest
+        @detail ? explain(@key) : effective(@key)
+      end
+
+      REGISTRY = Textus::Manifest::Schema::FIELD_REGISTRY
+      LEAN_FIELDS = REGISTRY.select { |_, m| m[:in_rule_explain].include?(:lean) }.keys.freeze
+      DETAIL_FIELDS = REGISTRY.select { |_, m| m[:in_rule_explain].include?(:detail) }.keys.freeze
+      EFFECTIVE_FIELDS = DETAIL_FIELDS.select { |f| REGISTRY[f][:policy_class] }.freeze
+
+      private
+
+      def effective(key)
+        set = @manifest.rules.for(key)
+        LEAN_FIELDS.each_with_object({}) do |field, out|
+          value = set.public_send(field)
+          out[field.to_s] = lean_value(field, value) unless value.nil?
+        end
+      end
+
+      def lean_value(field, value)
+        case field
+        when :retention
+          retention_hash(value, string_keys: true)
+        when :react
+          value.to_h
+        else
+          value
+        end
+      end
+
+      def explain(key)
+        matching = @manifest.rules.explain(key)
+        winners = @manifest.rules.for(key)
+        {
+          key: key,
+          matched_blocks: matching.map do |block|
+            { match: block.match }.merge(DETAIL_FIELDS.to_h { |f| [f, !block.public_send(f).nil?] })
+          end,
+          effective: EFFECTIVE_FIELDS.to_h { |f| [f, effective_value(f, winners.public_send(f))] },
+          guards: Textus::Gate::Auth::FLOOR.keys.to_h do |action|
+            floor = Textus::Gate::Auth::FLOOR.fetch(action, [])
+            rule = Array(@manifest.rules.for(key).guard&.dig(action.to_s))
+            [action, { floor: floor, rule: rule }]
+          end,
+        }
+      end
+
+      def effective_value(field, value)
+        return nil if value.nil?
+
+        case field
+        when :retention
+          retention_hash(value, string_keys: false)
+        when :react
+          value.to_h
+        else
+          value
+        end
+      end
+
+      def retention_hash(retention, string_keys:)
+        h = { ttl_seconds: retention.ttl_seconds, action: retention.action }
+        string_keys ? h.transform_keys(&:to_s) : h
+      end
+    end
+  end
+end