textus 0.54.2 → 0.55.2

data/lib/textus/action/key_mv.rb

@@ -1,129 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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

@@ -1,42 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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.system.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

@@ -1,52 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,91 +0,0 @@
-# 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

data/lib/textus/action/rule_lint.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Textus
-  module Action
-    class RuleLint < Base
-      extend Textus::Contract::DSL
-
-      verb :rule_lint
-      summary "Diff candidate manifest YAML's rules against the live manifest. No writes."
-      surfaces :cli, :mcp
-      cli "rule lint"
-      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
-                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
-      view { |v, _i| v.to_h }
-
-      def initialize(candidate_yaml:)
-        super()
-        @candidate_yaml = candidate_yaml
-      end
-
-      def call(container:, **)
-        root = container.root
-        live_rules = current_rules(root)
-        candidate_rules = parse_candidate(@candidate_yaml)
-
-        live_by_match = live_rules.to_h { |rule| [rule["match"], rule] }
-        candidate_by_match = candidate_rules.to_h { |rule| [rule["match"], rule] }
-
-        steps = (candidate_by_match.keys - live_by_match.keys).map do |match|
-          { "op" => "add_rule", "match" => match, "rule" => candidate_by_match[match] }
-        end
-        (live_by_match.keys - candidate_by_match.keys).each do |match|
-          steps << { "op" => "remove_rule", "match" => match }
-        end
-        (live_by_match.keys & candidate_by_match.keys).each do |match|
-          next if live_by_match[match] == candidate_by_match[match]
-
-          steps << {
-            "op" => "change_rule",
-            "match" => match,
-            "from" => live_by_match[match],
-            "to" => candidate_by_match[match],
-          }
-        end
-
-        Textus::Jobs::Plan.new(steps: steps, warnings: [])
-      end
-
-      private
-
-      def current_rules(root)
-        raw = YAML.safe_load_file(File.join(root, "manifest.yaml"), permitted_classes: [Symbol], aliases: false)
-        Array(raw["rules"])
-      end
-
-      def parse_candidate(yaml_text)
-        raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
-        raise UsageError.new("candidate is not a YAML mapping") unless raw.is_a?(Hash)
-
-        Array(raw["rules"])
-      rescue Psych::Exception => e
-        raise UsageError.new("candidate YAML parse error: #{e.message}")
-      end
-    end
-  end
-end