textus 0.51.0 → 0.53.0

data/lib/textus/{read → action}/blame.rb

@@ -1,34 +1,46 @@
+# frozen_string_literal: true
+
 require "open3"
 
 module Textus
-  module Read
-    # For one key, joins every audit-log row with the git commit (sha,
-    # author, date, subject) that introduced the file state at that audit
-    # row. Falls back to `git => nil` when not in a git repo or when the
-    # file is untracked.
-    class Blame
+  module Action
+    class Blame < Base
       extend Textus::Contract::DSL
 
-      verb     :blame
-      summary  "Annotate audit rows for a key with the git commit that introduced each file state."
+      verb :blame
+      summary "Annotate audit rows for a key with the git commit that introduced each file state."
       surfaces :cli
-      cli      "blame"
-      arg :key,   String,  required: true, positional: true, description: "entry key to blame"
+      cli "blame"
+      arg :key, String, required: true, positional: true, description: "entry key to blame"
       arg :limit, Integer, required: false, description: "maximum number of audit rows to return"
       view(:cli) { |rows, inputs| { "verb" => "blame", "key" => inputs[:key], "rows" => rows } }
 
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+      BURN = :sync
+
+      def initialize(key:, limit: nil)
+        super()
+        @key = key
+        @limit = limit
+      end
+
+      def call(container:, **)
         @container = container
-        @manifest  = container.manifest
-        @root      = container.root
+        @manifest = container.manifest
+        @root = container.root
+
+        audit_rows = Textus::Action::Audit.new(key: @key, limit: @limit).call(container: container)
+        path = resolve_path(@key)
+        return audit_rows.map { |row| row.merge("git" => nil) } unless git_tracked?(path)
+
+        audit_rows.map { |row| row.merge("git" => git_commit_at(path, timestamp: row["ts"])) }
       end
 
-      def call(key, limit: nil)
-        audit_rows = Textus::Read::Audit.new(container: @container).call(key: key, limit: limit)
-        path = resolve_path(key)
-        return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
 
-        audit_rows.map { |r| r.merge("git" => git_commit_at(path, timestamp: r["ts"])) }
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
       end
 
       private
@@ -37,9 +49,6 @@ module Textus
         res = @manifest.resolver.resolve(key)
         mentry = res.entry
         path = res.path
-        # Nested entries resolve to a file under the entry path; leaf entries
-        # already have a fully-resolved path. Either way `path` is what git
-        # needs to know about.
         path || Textus::Key::Path.resolve(@manifest.data, mentry)
       rescue Textus::Error
         nil
@@ -60,7 +69,6 @@ module Textus
       end
 
       def git_repo?
-        # Walk up from store root to find a .git directory.
         dir = @root
         loop do
           return true if File.directory?(File.join(dir, ".git"))

data/lib/textus/action/boot.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Boot < Base
+      extend Textus::Contract::DSL
+
+      verb :boot
+      summary "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
+      surfaces :cli, :mcp
+      arg :lean, :boolean,
+          description: "return only orientation essentials (zones, agent_quickstart, contract_etag) for cheap session-start injection"
+
+      BURN = :sync
+
+      def initialize(lean: nil)
+        super()
+        @lean = lean
+      end
+
+      def call(container:, **)
+        Textus::Boot.build(container: container, lean: !@lean.nil?)
+      end
+    end
+  end
+end

data/lib/textus/action/data_mv.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Textus
+  module Action
+    class DataMv < Base
+      extend Textus::Contract::DSL
+
+      verb :data_mv
+      summary "Rename a data lane — manifest + files. Refuses if destination exists."
+      surfaces :cli, :mcp
+      cli "data mv"
+      arg :from, String, required: true, positional: true, description: "current data lane name"
+      arg :to, String, required: true, positional: true,
+                       description: "new data lane name; refused if a lane by this name already exists"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, returns the planned zone move without applying it; " \
+                                           "defaults to false, so omitting it applies the move immediately"
+      view { |v, _i| v.to_h }
+
+      BURN = :sync
+
+      def initialize(from:, to:, dry_run: false)
+        super()
+        @from = from
+        @to = to
+        @dry_run = dry_run
+      end
+
+      def call(container:, **)
+        manifest = container.manifest
+        root = container.root
+
+        raise UsageError.new("from and to required") if @from.nil? || @to.nil? || @from.empty? || @to.empty?
+        raise UsageError.new("data lane '#{@from}' not declared") unless manifest.data.declared_lane_kinds.key?(@from)
+
+        dest_dir = File.join(root, "data", @to)
+        raise UsageError.new("destination 'data/#{@to}' already exists") if File.exist?(dest_dir)
+
+        affected_keys = manifest.data.entries.select { |entry| entry.lane == @from }.map(&:key)
+
+        steps = [{ "op" => "rename_zone", "from" => @from, "to" => @to }]
+        steps += affected_keys.map do |key|
+          { "op" => "mv", "from" => key, "to" => "#{@to}#{key[@from.length..]}" }
+        end
+
+        plan = Textus::Background::Plan.new(steps: steps, warnings: [])
+        return plan if @dry_run
+
+        rewrite_manifest!(root)
+        FileUtils.mv(File.join(root, "data", @from), dest_dir)
+        plan
+      end
+
+      private
+
+      def rewrite_manifest!(root)
+        path = File.join(root, "manifest.yaml")
+        raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+        raw["lanes"].each { |lane| lane["name"] = @to if lane["name"] == @from }
+        raw["entries"].each do |entry|
+          entry["lane"] = @to if entry["lane"] == @from
+          entry["key"] = entry["key"].sub(/\A#{Regexp.escape(@from)}(\.|\z)/, "#{@to}\\1")
+          entry["path"] = entry["path"].sub(%r{\A(data/)?#{Regexp.escape(@from)}(/|\z)}, "\\1#{@to}\\2")
+        end
+        File.write(path, YAML.dump(raw))
+      end
+    end
+  end
+end

data/lib/textus/action/deps.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Deps < Base
+      extend Textus::Contract::DSL
+
+      verb :deps
+      summary "List the keys a derived entry depends on (its projection/external sources)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key of the derived entry whose source keys you want"
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        entry = container.manifest.data.entries.find { |e| e.key == @key }
+        deps =
+          if entry&.derived?
+            src = entry.source
+            if src.projection?
+              Array(src.select).compact
+            elsif src.external?
+              Array(src.sources).compact
+            else
+              []
+            end
+          else
+            []
+          end
+        { "key" => @key, "deps" => deps.uniq }
+      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/doctor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Doctor < Base
+      extend Textus::Contract::DSL
+
+      verb :doctor
+      summary "Run health checks on the textus store and report any issues."
+      surfaces :cli
+      cli "doctor"
+      arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
+
+      BURN = :sync
+
+      def initialize(checks: nil)
+        super()
+        @checks = checks
+      end
+
+      def call(container:, call:, **)
+        Textus::Doctor.build(container: container, checks: @checks, role: call.role)
+      end
+    end
+  end
+end

data/lib/textus/action/drain.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Drain < Base
+      extend Textus::Contract::DSL
+
+      verb :drain
+      summary "Seed refresh + sweep jobs then drain the queue to empty. " \
+              "Identical to one Watcher tick. Use when no watcher is running."
+      surfaces :cli, :mcp
+      arg :prefix, String, description: "restrict to keys under this dotted prefix"
+      arg :lane,   String, description: "restrict to entries in this lane"
+
+      BURN = :sync
+
+      def initialize(prefix: nil, lane: nil)
+        super()
+        @prefix = prefix
+        @lane   = lane
+      end
+
+      def call(container:, call:)
+        queue = Textus::Ports::Queue.new(root: container.root)
+        Textus::Background::Planner::Plan.seed(
+          container: container,
+          queue: queue,
+          role: call.role,
+        )
+        queue.reclaim(now: Textus::Ports::Clock.new.now)
+        summary = Textus::Background::Worker.for(container:, queue:).drain
+        {
+          "protocol" => Textus::PROTOCOL,
+          "ok" => summary.failed.zero?,
+          "completed" => summary.completed,
+          "failed" => summary.failed,
+        }
+      end
+    end
+  end
+end

data/lib/textus/action/enqueue.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Enqueue < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :enqueue
+      summary "Push a registered job type onto the convergence queue, to be run by drain/serve."
+      surfaces :cli, :mcp
+      cli "enqueue"
+      arg :type, String, required: true, positional: true,
+                         description: "registered job type (e.g. materialize, re-pull, sweep)"
+      arg :args, Hash, default: {},
+                       description: "type-specific arguments (e.g. { key: ... } or { scope: ... })"
+
+      BURN = :sync
+
+      def initialize(type:, args: {})
+        super()
+        @type = type
+        @job_args = args
+      end
+
+      def args
+        { type: @type, args: @job_args }
+      end
+
+      def call(container:, call:)
+        action_class = begin
+          Textus::Background::Job.fetch(@type.to_s)
+        rescue Textus::UsageError
+          raise Textus::UsageError.new("unregistered job type '#{@type}'")
+        end
+        if action_class.const_defined?(:REQUIRED_ROLE) && call.role != action_class::REQUIRED_ROLE
+          raise Textus::Error.new(
+            "forbidden",
+            "role '#{call.role}' is not authorized to enqueue this job type (requires '#{action_class::REQUIRED_ROLE}')",
+            details: { "role" => call.role, "required_role" => action_class::REQUIRED_ROLE },
+            exit_code: 77,
+          )
+        end
+
+        job = Textus::Ports::Queue::Job.new(
+          type: @type,
+          args: @job_args,
+          enqueued_by: call.role,
+          max_attempts: 3,
+        )
+        Textus::Ports::Queue.new(root: container.root).enqueue(job)
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id }
+      end
+    end
+  end
+end

data/lib/textus/action/get.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Get < Base
+      extend Textus::Contract::DSL
+
+      verb :get
+      summary "Read one entry - a pure on-disk read annotated with a freshness " \
+              "verdict; never ingests (quarantine freshness is drain + hook " \
+              "only, ADR 0089). Returns the envelope (uid, etag, _meta, body, " \
+              "freshness)."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key to read, e.g. 'knowledge.project'"
+      view { |v, _i| v.to_h_for_wire }
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call:, file_stat: Textus::Ports::Storage::FileStat.new)
+        @container = container
+        @call = call
+        @manifest = container.manifest
+        @file_store = container.file_store
+        @file_stat = file_stat
+        annotated_envelope(@key)
+      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
+
+      private
+
+      def annotated_envelope(key)
+        envelope = read_raw_envelope(key)
+        return nil if envelope.nil?
+
+        entry = @manifest.resolver.resolve(key).entry
+        envelope.with(freshness: evaluator.verdict(entry))
+      end
+
+      def evaluator
+        @evaluator ||= Textus::Core::Freshness::Evaluator.new(
+          manifest: @manifest,
+          file_stat: @file_stat,
+          clock: @call,
+        )
+      end
+
+      def read_raw_envelope(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        return nil unless @file_store.exists?(path)
+
+        raw = @file_store.read(path)
+        parsed = Textus::Entry.for_format(mentry.format).parse(raw, path: path)
+        Textus::Envelope.build(
+          key: key,
+          mentry: mentry,
+          path: path,
+          meta: parsed["_meta"],
+          body: parsed["body"],
+          etag: Textus::Etag.for_bytes(raw),
+          content: parsed["content"],
+        )
+      end
+    end
+  end
+end

data/lib/textus/action/jobs.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Jobs < Base
+      extend Textus::Contract::DSL
+
+      verb :jobs
+      summary "List queued jobs by state; retry a dead-lettered job or purge a state."
+      surfaces :cli, :mcp
+      cli "jobs"
+      arg :state, String, default: "ready", description: "ready|leased|done|failed"
+      arg :action, String, default: nil, description: "retry|purge (optional)"
+      arg :job_id, String, default: nil, description: "job id (required for action=retry)"
+
+      BURN = :sync
+
+      def initialize(state: "ready", action: nil, job_id: nil)
+        super()
+        @state = state
+        @action = action
+        @job_id = job_id
+      end
+
+      def call(container:, **)
+        queue = Textus::Ports::Queue.new(root: container.root)
+        case @action
+        when "retry"
+          queue.retry_failed(@job_id)
+        when "purge"
+          queue.purge(@state)
+        end
+
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "state" => @state, "jobs" => queue.list(@state) }
+      end
+    end
+  end
+end

data/lib/textus/action/key_delete.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class KeyDelete < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :key_delete
+      summary "Delete one entry by key. Single-key, lower blast radius than key_delete_prefix; " \
+              "guarded by an optional optimistic-concurrency etag. Returns {ok, key, deleted}."
+      surfaces :cli, :mcp
+      cli "key delete"
+      arg :key, String, required: true, positional: true,
+                        description: "dotted entry key to delete"
+      arg :if_etag, String,
+          description: "optimistic-concurrency guard: the etag you last read; the delete is rejected if the entry changed since"
+
+      BURN = :sync
+
+      def initialize(key:, if_etag: nil)
+        super()
+        @key = key
+        @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: :key_delete, actor: call.role, key: @key, extra: { if_etag: @if_etag })
+
+          writer(container, call).delete(@key, mentry:, if_etag: @if_etag)
+
+          container.steps.publish(
+            :entry_deleted,
+            ctx: Textus::Step::Context.for(container: container, call: call),
+            key: @key,
+          )
+
+          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => @key, "deleted" => true }
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/key_delete_prefix.rb

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