textus 0.52.0 → 0.54.0

data/lib/textus/action/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    @registry = {}
+
+    def self.registry = @registry
+
+    def self.register(klass)
+      @registry[klass.name.gsub("::", "/").downcase] = klass
+    end
+
+    def self.fetch(type)
+      return @registry[type] if @registry[type]
+
+      match = @registry.values.find { |k| k.const_defined?(:TYPE, false) && type == k::TYPE }
+      raise Textus::UsageError.new("unknown action type: #{type}") unless match
+
+      @registry[type] = match
+    end
+
+    class Base
+      def self.inherited(subclass)
+        super
+        Textus::Action.register(subclass) if subclass.name
+      end
+
+      def call(**)
+        raise NotImplementedError.new("#{self.class}#call")
+      end
+
+      def args
+        params = self.class.instance_method(:initialize).parameters
+        names = params.select { |t,| %i[key keyreq].include?(t) }.map(&:last)
+        names.each_with_object({}) do |name, h|
+          val = instance_variable_get(:"@#{name}")
+          h[name] = val unless val.nil?
+        end
+      end
+    end
+  end
+end

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

@@ -1,34 +1,44 @@
+# 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
+      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 +47,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 +67,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,17 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Boot < Base
+      extend Textus::Contract::DSL
+
+      verb :boot
+      summary "Return the orientation contract: lanes, agent_quickstart, agent_protocol, and pre-computed artifacts."
+      surfaces :cli, :mcp
+
+      def call(container:, **)
+        Textus::Boot.build(container: container)
+      end
+    end
+  end
+end

data/lib/textus/action/data_mv.rb

@@ -0,0 +1,69 @@
+# 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 }
+
+      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::Jobs::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,34 @@
+# 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"
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        entry = container.manifest.data.entries.find { |e| e.key == @key }
+        deps = entry&.external? ? Array(entry.source&.sources).compact : []
+        { "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,24 @@
+# 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)"
+
+      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,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Drain < Base
+      extend Textus::Contract::DSL
+
+      verb :drain
+      summary "Seed materialize + 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"
+
+      def initialize(prefix: nil, lane: nil)
+        super()
+        @prefix = prefix
+        @lane   = lane
+      end
+
+      def call(container:, call:)
+        queue = Textus::Ports::JobStore.new(root: container.root)
+        Textus::Jobs::Planner.seed(
+          container: container,
+          queue: queue,
+          role: call.role,
+        )
+        queue.reclaim(now: Textus::Ports::Clock.new.now)
+        summary = Textus::Jobs::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,53 @@
+# 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: ... })"
+
+      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::Jobs.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::JobStore::Job.new(
+          type: @type,
+          args: @job_args,
+          enqueued_by: call.role,
+          max_attempts: 3,
+        )
+        Textus::Ports::JobStore.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,78 @@
+# 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 }
+
+      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::Format.for(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/ingest.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "date"
+
+module Textus
+  module Action
+    class Ingest < Base
+      extend Textus::Contract::DSL
+
+      verb :ingest
+      summary "Capture external source material into the raw lane. Write-once, agent-owned."
+      surfaces :cli, :mcp
+      arg :kind,  String, required: true, positional: true,
+                          description: "source kind: url | file | asset"
+      arg :slug,  String, required: true,
+                          description: "human slug for the key suffix (kebab-case)"
+      arg :url,   String, description: "remote URL (required when kind=url)"
+      arg :path,  String, description: "local file path (required when kind=file or kind=asset)"
+      arg :zone,  String, description: "asset group subdirectory (required when kind=asset)"
+      arg :label, String, description: "human label stored in source.label"
+      view { |env| { "key" => env.key, "uid" => env.uid, "etag" => env.etag } }
+
+      SOURCE_KINDS = %w[url file asset].freeze
+
+      def initialize(kind:, slug:, url: nil, path: nil, zone: nil, label: nil)
+        super()
+        @kind  = kind
+        @slug  = slug
+        @url   = url
+        @path  = path
+        @zone  = zone
+        @label = label
+      end
+
+      def call(container:, call:)
+        validate_inputs!
+
+        now = Time.now.utc
+        key = derive_key(now)
+
+        Textus::Gate::Auth.new(container).check_action!(
+          action: :ingest, actor: call.role, key: key,
+        )
+
+        write_raw_entry(key, now, container, call)
+      end
+
+      private
+
+      def validate_inputs!
+        unless SOURCE_KINDS.include?(@kind)
+          raise Textus::UsageError.new(
+            "ingest kind must be one of #{SOURCE_KINDS.join("|")}, got #{@kind.inspect}",
+          )
+        end
+        case @kind
+        when "url"
+          raise Textus::UsageError.new("ingest url requires --url") unless @url
+        when "file"
+          raise Textus::UsageError.new("ingest file requires --path") unless @path
+        when "asset"
+          raise Textus::UsageError.new("ingest asset requires --path") unless @path
+          raise Textus::UsageError.new("ingest asset requires --zone") unless @zone
+        end
+      end
+
+      def derive_key(now)
+        date = now.strftime("%Y.%m.%d")
+        "raw.#{date}.#{@kind}-#{@slug}"
+      end
+
+      def write_raw_entry(key, now, container, call)
+        ts     = now.iso8601
+        mentry = container.manifest.resolver.resolve(key).entry
+        writer = Textus::Envelope::Writer.from(container: container, call: call)
+
+        case @kind
+        when "url"
+          structured = {
+            "ingested_at" => ts,
+            "source" => { "kind" => "url", "url" => @url, "label" => @label || @url },
+            "body" => nil,
+          }
+          writer.put(key, mentry: mentry,
+                          payload: Textus::Envelope::Writer::Payload.new(
+                            meta: nil, body: nil, content: structured,
+                          ))
+        when "file"
+          body_content = File.read(@path)
+          structured = {
+            "ingested_at" => ts,
+            "source" => { "kind" => "file", "path" => @path,
+                          "label" => @label || File.basename(@path) },
+            "body" => body_content,
+          }
+          writer.put(key, mentry: mentry,
+                          payload: Textus::Envelope::Writer::Payload.new(
+                            meta: nil, body: nil, content: structured,
+                          ))
+        when "asset"
+          asset_rel = copy_asset_file(container, now)
+          structured = {
+            "ingested_at" => ts,
+            "source" => { "kind" => "asset",
+                          "label" => @label || File.basename(@path) },
+            "asset" => asset_rel,
+            "body" => nil,
+          }
+          writer.put(key, mentry: mentry,
+                          payload: Textus::Envelope::Writer::Payload.new(
+                            meta: nil, body: nil, content: structured,
+                          ))
+        end
+      end
+
+      def copy_asset_file(container, now)
+        date_path = now.strftime("%Y/%m/%d")
+        filename  = File.basename(@path)
+        assets_dir = File.join(container.root, "assets", "raw", date_path, @zone)
+        FileUtils.mkdir_p(assets_dir)
+        FileUtils.cp(@path, File.join(assets_dir, filename))
+        create_gitignore_sentinel(container)
+        "raw/#{date_path}/#{@zone}/#{filename}"
+      end
+
+      def create_gitignore_sentinel(container)
+        assets_root = File.join(container.root, "assets")
+        FileUtils.mkdir_p(assets_root)
+        sentinel = File.join(assets_root, ".gitignore")
+        File.write(sentinel, "*\n") unless File.exist?(sentinel)
+      end
+    end
+  end
+end

data/lib/textus/action/jobs.rb

@@ -0,0 +1,36 @@
+# 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)"
+
+      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::JobStore.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,36 @@
+# 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"
+
+      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
+
+          writer(container, call).delete(@key, mentry:, if_etag: @if_etag)
+
+          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => @key, "deleted" => true }
+        end
+      end
+    end
+  end
+end