textus 0.54.2 → 0.55.2

data/lib/textus/action/data_mv.rb

@@ -1,69 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,203 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "date"
-require "digest"
-
-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
-      CONTENT_HASH_ALGO = "sha256"
-      TOMBSTONE_RETAIN = %w[ingested_at].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,
-        )
-
-        content_hash = compute_content_hash
-        writer = Textus::Envelope::Writer.from(container: container, call: call)
-        mentry = container.manifest.resolver.resolve(key).entry
-        ts = now.iso8601
-        structured = build_structured(ts, container, now, content_hash)
-
-        index = Textus::Ports::RawIndex.new(root: container.root)
-        duplicate_key = find_duplicate(index, content_hash)
-
-        if duplicate_key && duplicate_key != key
-          supersede_entry(duplicate_key, key, structured, container, call, index)
-        else
-          env = write_raw_entry(key, structured, mentry, writer)
-          index.upsert(content_hash: content_hash, url: @url, key: key)
-          env
-        end
-      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 compute_content_hash
-        digest = Digest::SHA256.new
-        case @kind
-        when "url"
-          digest.update(@url)
-        when "file", "asset"
-          digest.file(@path)
-        end
-        "#{CONTENT_HASH_ALGO}:#{digest.hexdigest}"
-      end
-
-      def build_structured(timestamp, container, now, content_hash)
-        base = { "ingested_at" => timestamp, "content_hash" => content_hash }
-        case @kind
-        when "url"
-          base.merge("source" => { "kind" => "url", "url" => @url, "label" => @label || @url },
-                     "body" => nil)
-        when "file"
-          body_content = File.read(@path)
-          base.merge("source" => { "kind" => "file", "path" => @path,
-                                   "label" => @label || File.basename(@path) },
-                     "body" => body_content)
-        when "asset"
-          asset_rel = copy_asset_file(container, now)
-          base.merge("source" => { "kind" => "asset",
-                                   "label" => @label || File.basename(@path) },
-                     "asset" => asset_rel,
-                     "body" => nil)
-        end
-      end
-
-      def write_raw_entry(key, structured, mentry, writer)
-        writer.put(key, mentry: mentry,
-                        payload: Textus::Envelope::Writer::Payload.new(
-                          meta: nil, body: nil, content: structured,
-                        ))
-      end
-
-      def find_duplicate(index, content_hash)
-        dup = index.find_by_hash(content_hash)
-        return dup if dup
-
-        return unless @kind == "url"
-
-        index.find_by_url(@url)
-      end
-
-      def supersede_entry(old_key, new_key, structured, container, call, index)
-        old_mentry = container.manifest.resolver.resolve(old_key).entry
-        writer = Textus::Envelope::Writer.from(container: container, call: call)
-
-        reader = Textus::Envelope::Reader.from(container: container)
-        old_env = reader.read(old_key)
-        old_content = old_env&.content || {}
-        tombstone = {}
-        TOMBSTONE_RETAIN.each do |k|
-          tombstone[k] = old_content[k] if old_content.key?(k)
-        end
-        source_kind = old_content.dig("source", "kind")
-        tombstone["source"] = { "kind" => source_kind } if source_kind
-        tombstone["superseded_by"] = new_key
-
-        writer.put(old_key, mentry: old_mentry,
-                            payload: Textus::Envelope::Writer::Payload.new(
-                              meta: nil, body: nil, content: tombstone,
-                            ))
-
-        structured["supersedes"] = old_key
-        env = write_raw_entry(new_key, structured, container.manifest.resolver.resolve(new_key).entry, writer)
-
-        move_asset_file(container, old_content["asset"]) if @kind == "asset" && old_content["asset"]
-
-        index.upsert(content_hash: structured["content_hash"], url: @url, key: new_key)
-        env
-      end
-
-      def move_asset_file(container, old_asset_rel)
-        old_path = File.join(container.root, "assets", old_asset_rel)
-        return unless File.exist?(old_path)
-
-        now = Time.now.utc
-        date_path = now.strftime("%Y/%m/%d")
-        filename = File.basename(old_path)
-        new_dir = File.join(container.root, "assets", "raw", date_path, @zone)
-        new_path = File.join(new_dir, filename)
-
-        return if old_path == new_path
-
-        FileUtils.mkdir_p(new_dir)
-        FileUtils.mv(old_path, new_path)
-      rescue Errno::ENOENT, Errno::EACCES => e
-        warn "[textus ingest] could not move asset #{old_asset_rel}: #{e.message}"
-      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

@@ -1,36 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# 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

data/lib/textus/action/key_delete_prefix.rb

@@ -1,44 +0,0 @@
-# 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 }
-
-      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::Jobs::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