textus 0.52.0 → 0.53.0

data/lib/textus/action/list.rb

@@ -0,0 +1,44 @@
+# 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 } }
+
+      BURN = :sync
+
+      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,54 @@
+# 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 }
+
+      BURN = :sync
+
+      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,26 @@
+# 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"
+
+      BURN = :sync
+
+      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/scanner.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Textus
+  module Action
+    class Pulse
+      class Scanner
+        def initialize(prefix: nil, lane: nil)
+          @prefix = prefix
+          @lane   = lane
+        end
+
+        def call(container:, call:)
+          @container  = container
+          @call       = call
+          @manifest   = container.manifest
+          @file_store = container.file_store
+
+          rows = []
+          @manifest.data.entries.each do |mentry|
+            next if @prefix && !mentry.key.start_with?(@prefix)
+            next if @lane   && mentry.lane != @lane
+
+            rows << row_for(mentry)
+          end
+          rows
+        end
+
+        private
+
+        def row_for(mentry)
+          envelope = safe_get(mentry.key)
+          last = envelope&.meta&.dig("last_fetched_at")
+          ttl, action = policy_for(mentry)
+          return base_row(mentry, last).merge(status: :no_policy) if ttl.nil?
+
+          basis = basis_for(mentry)
+          expired = expired?(mentry, basis, ttl)
+          base_row(mentry, last).merge(
+            ttl_seconds: ttl,
+            action: action,
+            status: expired ? :expired : :fresh,
+            next_due_at: basis.nil? ? nil : (basis + ttl).utc.iso8601,
+          )
+        end
+
+        def policy_for(mentry)
+          if mentry.intake?
+            ttl = mentry.source.ttl_seconds
+            return [ttl, :refresh] unless ttl.nil?
+          end
+          ret = @manifest.rules.for(mentry.key).retention
+          return [ret.ttl_seconds, ret.action] unless ret.nil?
+
+          [nil, nil]
+        end
+
+        def basis_for(mentry)
+          return evaluator.intake_basis(mentry) if mentry.intake? && mentry.source.ttl_seconds
+
+          mtime_for(mentry.key)
+        end
+
+        def expired?(mentry, basis, ttl)
+          if mentry.intake? && mentry.source.ttl_seconds
+            evaluator.verdict(mentry).stale
+          else
+            basis.nil? || Textus::Core::Retention::Sweep.expired?(ttl_seconds: ttl, mtime: basis, now: @call.now)
+          end
+        end
+
+        def evaluator
+          @evaluator ||= Textus::Core::Freshness::Evaluator.new(
+            manifest: @manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+            clock: @call,
+          )
+        end
+
+        def mtime_for(key)
+          path = @manifest.resolver.resolve(key).path
+          @file_store.exists?(path) ? Textus::Ports::Storage::FileStat.new.mtime(path) : nil
+        rescue Textus::Error
+          nil
+        end
+
+        def base_row(mentry, last)
+          {
+            key: mentry.key,
+            lane: mentry.lane,
+            last_fetched_at: last,
+            age_seconds: last ? (@call.now - Time.parse(last)).to_i : nil,
+          }
+        end
+
+        def safe_get(key)
+          res = @manifest.resolver.resolve(key)
+          return nil unless @file_store.exists?(res.path)
+
+          raw = @file_store.read(res.path)
+          parsed = Textus::Entry.for_format(res.entry.format).parse(raw, path: res.path)
+          Textus::Envelope.build(
+            key: key,
+            mentry: res.entry,
+            path: res.path,
+            meta: parsed["_meta"],
+            body: parsed["body"],
+            etag: Textus::Etag.for_bytes(raw),
+            content: parsed["content"],
+          )
+        rescue Textus::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/pulse.rb

@@ -0,0 +1,87 @@
+# 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, stale, pending proposals, doctor summary."
+      surfaces :cli, :mcp
+      around :cursor
+      arg :since, Integer, session_default: :cursor,
+                           description: "audit seq to diff from; defaults to the session cursor"
+
+      BURN = :sync
+
+      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
+        @steps = container.steps
+
+        freshness_rows = Pulse::Scanner.new.call(container: container, call: call)
+        {
+          "cursor" => @audit_log.latest_seq,
+          "changed" => Textus::Action::Audit.new(seq_since: @since).call(container: container),
+          "stale" => freshness_rows.select { |row| row[:status] == :expired }.map { |row| row[:key] },
+          "pending_review" => review_keys,
+          "doctor" => doctor_summary,
+          "contract_etag" => Textus::Etag.for_contract(@root),
+          "next_due_at" => soonest_due(freshness_rows),
+          "hook_errors" => hook_errors_since(@since || 0),
+        }
+      end
+
+      private
+
+      def soonest_due(rows)
+        times = rows.map { |row| row[:next_due_at] }.compact.map { |t| Time.parse(t) }
+        return nil if times.empty?
+
+        times.min.utc.iso8601
+      end
+
+      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 doctor_summary
+        result = Textus::Doctor.build(container: @container)
+        issues = result["issues"] || []
+        {
+          "ok" => result["ok"],
+          "warn" => issues.count { |i| i["level"] == "warning" },
+          "fail" => issues.count { |i| i["level"] == "error" },
+        }
+      end
+
+      def hook_errors_since(seq)
+        @steps.error_log.since(seq).map do |row|
+          {
+            "seq" => row[:seq],
+            "event" => row[:event].to_s,
+            "hook" => row[:hook].to_s,
+            "key" => row[:key],
+            "error_class" => row[:error_class],
+            "error_message" => row[:error_message],
+            "at" => row[:at],
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/put.rb

@@ -0,0 +1,63 @@
+# 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 } }
+
+      BURN = :sync
+
+      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
+          auth(container).check_action!(action: :put, actor: call.role, key: @key, extra: { if_etag: @if_etag })
+
+          envelope = writer(container, call).put(
+            @key,
+            mentry: mentry,
+            payload: Textus::Envelope::IO::Writer::Payload.new(
+              meta: @meta,
+              body: @body,
+              content: @content,
+            ),
+            if_etag: @if_etag,
+          )
+
+          container.steps.publish(
+            :entry_written,
+            ctx: Textus::Step::Context.for(container: container, call: call),
+            key: @key,
+            envelope: envelope,
+          )
+
+          envelope
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/rdeps.rb

@@ -0,0 +1,49 @@
+# 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"
+
+      BURN = :sync
+
+      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.derived?
+
+          src = entry.source
+          sources =
+            if src.projection?
+              Array(src.select).compact
+            elsif src.external?
+              Array(src.sources).compact
+            else
+              []
+            end
+          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,49 @@
+# 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"
+
+      BURN = :sync
+
+      def initialize(pending_key:)
+        super()
+        @pending_key = pending_key
+      end
+
+      def call(container:, call:)
+        run_with_cascade(@pending_key, container:, call:) do
+          auth = Textus::Gate::Auth.new(container)
+          auth.check_action!(action: :reject, actor: call.role, key: @pending_key)
+
+          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)
+
+          container.steps.publish(
+            :proposal_rejected,
+            ctx: Textus::Step::Context.for(container: container, call: call),
+            key: @pending_key,
+            target_key: target_key,
+          )
+
+          { "protocol" => PROTOCOL, "rejected" => @pending_key, "target_key" => target_key }
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/rule_explain.rb

@@ -0,0 +1,95 @@
+# 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)) }
+
+      BURN = :sync
+
+      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
+        when :handler_permit
+          value.handlers
+        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

@@ -0,0 +1,70 @@
+# 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 }
+
+      BURN = :sync
+
+      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::Background::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