textus 0.55.1 → 0.56.0

data/lib/textus/action/key_mv_prefix.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class KeyMvPrefix < Base
-      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 self.call(container:, call:, from_prefix:, to_prefix:, dry_run: false)
-        return Failure(code: :usage_error, message: "from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
-
-        leaves = Textus::Action::List.leaf_keys(container: container, prefix: from_prefix)
-
-        if leaves.include?(from_prefix)
-          return Failure(code: :usage_error,
-                         message: "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::Store::Jobs::Plan.new(steps: steps, warnings: warnings)
-        return Success(plan) if dry_run
-
-        steps.each do |step|
-          Value::Result.unwrap(Textus::Action::KeyMv.call(container: container, call: call, old_key: step["from"], new_key: step["to"]))
-        end
-        Success(plan)
-      end
-    end
-  end
-end

data/lib/textus/action/list.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class List < Base
-      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 self.call(container:, call: nil, prefix: nil, lane: 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
-        Success(rows.map { |row| { "key" => row[:key], "lane" => row[:manifest_entry].lane, "path" => row[:path] } })
-      end
-
-      def self.leaf_keys(container:, prefix: nil, lane: nil)
-        rows = Value::Result.unwrap(call(container: container, prefix: prefix, lane: lane))
-        rows.map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
-      end
-    end
-  end
-end

data/lib/textus/action/propose.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Propose < Base
-      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 self.call(container:, call:, key:, meta: nil, body: nil, content: nil)
-        zone = container.manifest.policy.propose_lane_for(call.role)
-        unless zone
-          return Failure(code: :propose_forbidden,
-                         message: "role '#{call.role}' has no writable propose_lane",
-                         details: { "role" => call.role })
-        end
-
-        mentry = container.manifest.resolver.resolve("#{zone}.#{key}").entry
-        Success(container.compositor.write(
-                  "#{zone}.#{key}",
-                  mentry: mentry,
-                  payload: Textus::Store::Envelope::Writer::Payload.new(
-                    meta: meta || {},
-                    body: body,
-                    content: content,
-                  ),
-                  call: call,
-                ))
-      end
-    end
-  end
-end

data/lib/textus/action/published.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Published < Base
-      verb :published
-      summary "List all entries that declare a publish_to target."
-      surfaces :cli
-      cli "published"
-
-      def args
-        {}
-      end
-
-      def self.call(container:, **)
-        Success(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,49 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Textus
-  module Action
-    class Pulse < Base
-      verb :pulse
-      summary "Delta since cursor — changed entries, pending proposals, index freshness."
-      surfaces :cli, :mcp
-      arg :since, Integer, session_default: :cursor,
-                           description: "audit seq to diff from; defaults to the session cursor"
-
-      def self.call(container:, call:, since: nil, **)
-        manifest = container.manifest
-        audit_log = container.audit_log
-        root = container.root
-        since ||= Textus::Store::Cursor.new(root: root, role: call.role).read
-
-        changed = Value::Result.unwrap(Textus::Action::Audit.call(container: container, seq_since: since))
-
-        result = {
-          "cursor" => audit_log.latest_seq,
-          "changed" => changed,
-          "pending_review" => review_keys(manifest, container),
-          "contract_etag" => Textus::Value::Etag.for_contract(root),
-          "index_etag" => index_etag(container),
-        }
-
-        Textus::Store::Cursor.new(root: root, role: call.role).write(result["cursor"])
-        Success(result)
-      end
-
-      def self.review_keys(manifest, container)
-        queue = manifest.policy.queue_lane
-        return [] unless queue
-
-        Textus::Action::List.leaf_keys(container: container, lane: queue)
-      end
-
-      def self.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,38 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Put < Base
-      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 self.call(container:, call:, key:, meta: nil, body: nil, content: nil, if_etag: nil) # rubocop:disable Metrics/ParameterLists
-        Textus::Manifest::Data.validate_key!(key)
-        mentry = container.manifest.resolver.resolve(key).entry
-        Success(container.compositor.write(
-                  key,
-                  mentry: mentry,
-                  payload: Textus::Store::Envelope::Writer::Payload.new(
-                    meta: meta,
-                    body: body,
-                    content: content,
-                  ),
-                  if_etag: if_etag,
-                  call: call,
-                ))
-      end
-    end
-  end
-end

data/lib/textus/action/rdeps.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Rdeps < Base
-      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 self.call(container:, key:, **)
-        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
-        Success({ "key" => key, "rdeps" => rdeps })
-      end
-    end
-  end
-end

data/lib/textus/action/reject.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Reject < Base
-      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 self.call(container:, call:, pending_key:)
-        mentry = container.manifest.resolver.resolve(pending_key).entry
-        unless mentry.in_proposal_lane?(container.manifest.policy)
-          return Failure(code: :proposal_error, message: "reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.lane})")
-        end
-
-        env = container.compositor.read(pending_key)
-        parsed = proposal_from(env, key: pending_key)
-        return parsed if parsed.is_a?(Dry::Monads::Result::Failure)
-
-        target_key = parsed[:target_key]
-        container.compositor.delete(pending_key, mentry: mentry, call: call)
-        Success("protocol" => Textus::PROTOCOL, "rejected" => pending_key, "target_key" => target_key)
-      end
-    end
-  end
-end

data/lib/textus/action/rule_explain.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class RuleExplain < Base
-      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 self.call(container:, call:, key:, detail: nil) # rubocop:disable Lint/UnusedMethodArgument
-        manifest = container.manifest
-        Success(detail ? explain(manifest, key) : effective(manifest, 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
-
-      def self.effective(manifest, 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 self.lean_value(field, value)
-        case field
-        when :retention
-          retention_hash(value, string_keys: true)
-        when :react
-          value.to_h
-        else
-          value
-        end
-      end
-
-      def self.explain(manifest, 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 self.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 self.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,62 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Textus
-  module Action
-    class RuleLint < Base
-      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 self.call(container:, call:, candidate_yaml:) # rubocop:disable Lint/UnusedMethodArgument
-        root = container.root
-        live_rules = current_rules(root)
-        candidate_result = parse_candidate(candidate_yaml)
-        return candidate_result if candidate_result.is_a?(Dry::Monads::Result::Failure)
-
-        candidate_rules = candidate_result
-
-        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
-
-        Success(Textus::Store::Jobs::Plan.new(steps: steps, warnings: []))
-      end
-
-      def self.current_rules(root)
-        raw = YAML.safe_load_file(File.join(root, "manifest.yaml"), permitted_classes: [Symbol], aliases: false)
-        Array(raw["rules"])
-      end
-
-      def self.parse_candidate(yaml_text)
-        raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
-        return Failure(code: :usage_error, message: "candidate is not a YAML mapping") unless raw.is_a?(Hash)
-
-        Array(raw["rules"])
-      rescue Psych::Exception => e
-        Failure(code: :usage_error, message: "candidate YAML parse error: #{e.message}")
-      end
-    end
-  end
-end

data/lib/textus/action/rule_list.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class RuleList < Base
-      verb :rule_list
-      summary "List every rule block in the manifest."
-      surfaces :cli
-      cli "rule list"
-      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
-
-      def self.call(container:, call:, **_options) # rubocop:disable Lint/UnusedMethodArgument
-        manifest = container.manifest
-        Success(manifest.rules.blocks.map do |block|
-          row = { "match" => block.match }
-          LIST_FIELDS.each do |field|
-            value = block.public_send(field)
-            row[field.to_s] = serialize(field, value) unless value.nil?
-          end
-          row
-        end)
-      end
-
-      LIST_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_rule_list] }.keys.freeze
-
-      def self.serialize(field, value)
-        case field
-        when :retention
-          { "ttl_seconds" => value.ttl_seconds, "action" => value.action.to_s }
-        when :react
-          value.to_h
-        else
-          value
-        end
-      end
-    end
-  end
-end

data/lib/textus/action/schema_envelope.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class SchemaEnvelope < Base
-      verb :schema_show
-      summary "Return the schema (field shape) for an entry's family, by key."
-      surfaces :cli, :mcp
-      cli "schema show"
-      arg :key, String, required: true, positional: true,
-                        description: "any key in the family whose schema you want; returns required/optional fields and their types"
-
-      def self.call(container:, key:, **)
-        manifest = container.manifest
-        schemas = container.schemas
-        mentry = manifest.resolver.resolve(key).entry
-        schema = schemas.fetch_or_nil(mentry.schema)
-        Success({ "protocol" => Textus::PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h })
-      end
-    end
-  end
-end

data/lib/textus/action/uid.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Uid < Base
-      verb :uid
-      summary "Return the stable UID of an entry without reading its body."
-      surfaces :cli
-      cli "key uid"
-      arg :key, String, required: true, positional: true, description: "entry key"
-      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
-
-      def self.call(container:, call:, key:)
-        envelope = Value::Result.unwrap(Textus::Action::Get.call(container: container, call: call, key: key))
-        Success(envelope.uid)
-      end
-    end
-  end
-end

data/lib/textus/action/where.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Where < Base
-      verb :where
-      summary "Resolve a key to its zone, owner, and path without reading the body."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true,
-                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
-
-      def self.call(container:, key:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        manifest = container.manifest
-        res = manifest.resolver.resolve(key)
-        mentry = res.entry
-        path = res.path
-        Success({ "protocol" => Textus::PROTOCOL, "key" => key, "lane" => mentry.lane, "owner" => mentry.owner, "path" => path })
-      end
-    end
-  end
-end