textus 0.51.0 → 0.53.0

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

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