textus 0.55.2 → 0.56.0

data/lib/textus/format/markdown.rb

@@ -1,59 +0,0 @@
-require "yaml"
-
-module Textus
-  module Format
-    class Markdown < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-        return { "_meta" => {}, "body" => raw, "content" => nil } unless raw.start_with?("---\n") || raw.start_with?("---\r\n")
-
-        lines = raw.split(/\r?\n/, -1)
-        close_idx = lines[1..].index("---")
-        raise BadFrontmatter.new(path, "frontmatter not terminated") unless close_idx
-
-        close_idx += 1
-        fm_yaml = lines[1...close_idx].join("\n")
-        body = lines[(close_idx + 1)..].join("\n")
-        begin
-          fm = fm_yaml.strip.empty? ? {} : ::YAML.safe_load(fm_yaml, permitted_classes: [Date, Time], aliases: false)
-        rescue Psych::SyntaxError => e
-          raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
-        end
-        fm = {} unless fm.is_a?(Hash)
-        { "_meta" => fm, "body" => body, "content" => nil }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        _ = content
-        fm_yaml = meta.empty? ? "" : ::YAML.dump(meta).sub(/\A---\n/, "")
-        body = body.to_s
-        body += "\n" unless body.empty? || body.end_with?("\n")
-        "---\n#{fm_yaml}---\n#{body}"
-      end
-
-      def self.extensions = [".md"]
-
-      def self.nested_glob = "**/*.md"
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        _ = path
-        _ = content
-        bytes = serialize(meta: meta || {}, body: body.to_s)
-        [bytes, meta, body.to_s, nil]
-      end
-
-      def self.validate_path_extension(path, _nested)
-        ext = File.extname(path)
-        return if ["", ".md"].include?(ext)
-
-        raise UsageError.new("markdown format requires '.md' path (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: (data["body"] || "").to_s, content: nil }
-      end
-    end
-  end
-end

data/lib/textus/format/text.rb

@@ -1,55 +0,0 @@
-module Textus
-  module Format
-    class Text < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-
-        { "_meta" => {}, "body" => raw, "content" => nil }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        _ = meta
-        _ = content
-        b = body.to_s
-        b += "\n" unless b.empty? || b.end_with?("\n")
-        b
-      end
-
-      def self.extensions = [".txt"]
-
-      def self.nested_glob = "**/*.txt"
-
-      def self.enforce_name_match!(_path, _meta); end
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        _ = path
-        _ = content
-        bytes = serialize(meta: meta || {}, body: body.to_s)
-        [bytes, meta, body.to_s, nil]
-      end
-
-      def self.rewrite_name(_path, _basename) # rubocop:disable Naming/PredicateMethod
-        false
-      end
-
-      def self.validate_path_extension(path, nested)
-        ext = File.extname(path)
-        if nested
-          return if ext == ""
-
-          raise UsageError.new("nested text path must not have an extension")
-        end
-
-        return if [".txt", ""].include?(ext)
-
-        raise UsageError.new("text format requires '.txt' or no extension (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: (data["body"] || "").to_s, content: nil }
-      end
-    end
-  end
-end

data/lib/textus/format/yaml.rb

@@ -1,104 +0,0 @@
-require "yaml"
-
-module Textus
-  module Format
-    class Yaml < Base
-      def self.parse(raw, path: nil)
-        raw = raw.dup.force_encoding(Encoding::UTF_8)
-        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
-
-        begin
-          parsed = ::YAML.safe_load(raw, permitted_classes: [Date, Time], aliases: false)
-        rescue Psych::SyntaxError, Psych::AliasesNotEnabled, Psych::DisallowedClass => e
-          raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
-        end
-        raise BadFrontmatter.new(path, "YAML top-level must be a mapping") unless parsed.is_a?(Hash)
-
-        meta = parsed["_meta"]
-        fm = meta.is_a?(Hash) ? meta : {}
-        content_without_meta = parsed.except("_meta")
-        { "_meta" => fm, "body" => raw, "content" => content_without_meta }
-      end
-
-      def self.serialize(meta:, body:, content: nil)
-        if content.is_a?(Hash)
-          on_disk = meta && !meta.empty? ? { "_meta" => meta }.merge(content) : content
-          ::YAML.dump(on_disk).sub(/\A---\n/, "")
-        elsif body && !body.to_s.empty?
-          b = body.to_s
-          b += "\n" unless b.end_with?("\n")
-          b
-        else
-          raise UsageError.new("yaml serialize requires :content or :body")
-        end
-      end
-
-      def self.validate_against(schema, parsed)
-        schema.validate!(parsed["content"] || {})
-      end
-
-      RAW_REQUIRED = %w[ingested_at content_hash].freeze
-      RAW_SOURCE_KINDS = %w[url file asset].freeze
-
-      def self.validate_raw_entry!(parsed, lane)
-        return unless lane == "raw"
-
-        content = parsed["content"] || {}
-        return if content["superseded_by"]
-
-        missing = RAW_REQUIRED.reject { |f| content[f] }
-        raise Textus::BadContent.new(nil, "raw entry missing required field(s): #{missing.join(", ")}") if missing.any?
-
-        source = content["source"] || {}
-        kind = source["kind"]
-        unless RAW_SOURCE_KINDS.include?(kind)
-          raise Textus::BadContent.new(
-            nil, "raw entry source.kind must be #{RAW_SOURCE_KINDS.join("|")}, got #{kind.inspect}"
-          )
-        end
-
-        return unless kind == "url" && !source["url"]
-
-        raise Textus::BadContent.new(nil, "raw entry with source.kind=url must have source.url")
-      end
-
-      def self.extensions = [".yaml", ".yml"]
-
-      def self.nested_glob = "**/*.{yaml,yml}"
-
-      def self.serialize_for_put(meta:, body:, content:, path:)
-        raise UsageError.new("put for yaml requires content: or body:") if content.nil? && (body.nil? || body.to_s.empty?)
-
-        if content.nil?
-          begin
-            parsed = parse(body.to_s, path: path)
-          rescue BadFrontmatter => e
-            raise BadContent.new(path, "bad_content: #{e.message}")
-          end
-          [body.to_s, parsed["_meta"], body.to_s, parsed["content"]]
-        else
-          bytes = serialize(meta: meta, body: "", content: content)
-          [bytes, meta, bytes, content]
-        end
-      end
-
-      def self.validate_path_extension(path, nested)
-        ext = File.extname(path)
-        if nested
-          return if ext == ""
-
-          raise UsageError.new("nested yaml path must not have an extension")
-        end
-
-        return if [".yaml", ".yml"].include?(ext)
-
-        raise UsageError.new("yaml format requires '.yaml' or '.yml' path (got #{ext.inspect})")
-      end
-
-      def self.data_to_payload(data)
-        data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-        { meta: data["_meta"] || {}, body: nil, content: data["content"] || data }
-      end
-    end
-  end
-end

data/lib/textus/format.rb

@@ -1,61 +0,0 @@
-module Textus
-  module Format
-    SEP = "---".freeze
-
-    STRATEGIES = {
-      "markdown" => -> { Format::Markdown },
-      "json" => -> { Format::Json },
-      "yaml" => -> { Format::Yaml },
-      "text" => -> { Format::Text },
-    }.freeze
-
-    # Optional registry for injectable format strategies. Tests or app
-    # initializers can set Format.registry = { "custom" => -> { MyFormat }}
-    @registry = nil
-
-    def self.registry=(reg)
-      @registry = reg
-    end
-
-    def self.registry
-      @registry
-    end
-
-    EXT_TO_FORMAT = {
-      ".md" => "markdown",
-      ".json" => "json",
-      ".yaml" => "yaml",
-      ".yml" => "yaml",
-      ".txt" => "text",
-    }.freeze
-
-    def self.for(format)
-      key = format.to_s
-      return registry.fetch(key).call if registry&.key?(key)
-
-      STRATEGIES.fetch(key) { raise Textus::UsageError.new("unknown entry format: #{format.inspect}") }.call
-    end
-
-    def self.infer_from_extension(ext)
-      EXT_TO_FORMAT[ext]
-    end
-
-    def self.formats
-      EXT_TO_FORMAT.values.uniq
-    end
-
-    def self.parse(raw, path: nil, format: "markdown")
-      Format.for(format).parse(raw, path: path)
-    end
-
-    def self.serialize(meta: {}, body: "", content: nil, format: "markdown")
-      Format.for(format).serialize(meta: meta, body: body, content: content)
-    end
-
-    def self.data_to_payload(data, format)
-      return { meta: {}, body: "", content: nil } if data.nil?
-
-      Format.for(format).data_to_payload(data)
-    end
-  end
-end

data/lib/textus/handlers/maintenance/boot_store.rb

@@ -1,15 +0,0 @@
-module Textus
-  module Handlers
-    module Maintenance
-      class BootStore
-        def initialize(container:)
-          @container = container
-        end
-
-        def call(_command, _call)
-          Value::Result.success(Textus::Boot.build(container: @container))
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/maintenance/doctor_store.rb

@@ -1,15 +0,0 @@
-module Textus
-  module Handlers
-    module Maintenance
-      class DoctorStore
-        def initialize(container:)
-          @container = container
-        end
-
-        def call(command, call)
-          Value::Result.success(Textus::Doctor.build(container: @container, checks: command.checks, role: call.role))
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/maintenance/drain_store.rb

@@ -1,21 +0,0 @@
-module Textus
-  module Handlers
-    module Maintenance
-      class DrainStore
-        def initialize(container:, job_store:)
-          @container = container
-          @job_store = job_store
-        end
-
-        def call(_command, call)
-          queue = Textus::Store::Jobs::Queue.new(store: @job_store)
-          Textus::Store::Jobs::Planner.seed(container: @container, queue: queue, role: call.role)
-          queue.reclaim(now: Textus::Port::Clock.new.now)
-          summary = Textus::Store::Jobs::Worker.for(container: @container, queue: queue).drain
-          Value::Result.success("protocol" => Textus::PROTOCOL, "ok" => summary.failed.zero?,
-                                "completed" => summary.completed, "failed" => summary.failed)
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/maintenance/ingest_entry.rb

@@ -1,159 +0,0 @@
-require "fileutils"
-require "date"
-require "digest"
-
-module Textus
-  module Handlers
-    module Maintenance
-      class IngestEntry
-        SOURCE_KINDS = %w[url file asset].freeze
-        CONTENT_HASH_ALGO = "sha256"
-
-        def initialize(container:)
-          @container = container
-        end
-
-        def call(command, call)
-          unless SOURCE_KINDS.include?(command.kind)
-            return Value::Result.failure(:usage_error,
-                                         "ingest kind must be one of #{SOURCE_KINDS.join("|")}")
-          end
-
-          case command.kind
-          when "url"   then return Value::Result.failure(:usage_error, "ingest url requires url") unless command.url
-          when "file"  then return Value::Result.failure(:usage_error, "ingest file requires path") unless command.path
-          when "asset"
-            return Value::Result.failure(:usage_error, "ingest asset requires path") unless command.path
-            return Value::Result.failure(:usage_error, "ingest asset requires lane") unless command.lane
-          end
-
-          now = Time.now.utc
-          key = derive_key(now, command.kind, command.slug)
-          content_hash = compute_content_hash(command)
-          mentry = @container.manifest.resolver.resolve(key).entry
-          ts = now.iso8601
-
-          structured = build_structured(ts, now, content_hash, command)
-          store = @container.job_store
-          index = Textus::Store::Index::Lookup.new(store:)
-
-          duplicate_key = find_duplicate(index, content_hash, command)
-
-          env = if duplicate_key && duplicate_key != key
-                  supersede_entry(duplicate_key, key, structured, call, store, command)
-                else
-                  write_entry(key, structured, mentry, call)
-                end
-
-          rebuild_index(store)
-          Value::Result.success(env)
-        end
-
-        private
-
-        def derive_key(now, kind, slug)
-          date = now.strftime("%Y.%m.%d")
-          "raw.#{date}.#{kind}-#{slug}"
-        end
-
-        def compute_content_hash(command)
-          digest = Digest::SHA256.new
-          case command.kind
-          when "url" then digest.update(command.url)
-          when "file", "asset" then digest.file(command.path)
-          end
-          "#{CONTENT_HASH_ALGO}:#{digest.hexdigest}"
-        end
-
-        def build_structured(timestamp, now, content_hash, command)
-          base = { "ingested_at" => timestamp, "content_hash" => content_hash }
-          case command.kind
-          when "url"
-            base.merge("source" => { "kind" => "url", "url" => command.url,
-                                     "label" => command.label || command.url }, "body" => nil)
-          when "file"
-            base.merge("source" => { "kind" => "file", "path" => command.path,
-                                     "label" => command.label || File.basename(command.path) },
-                       "body" => File.read(command.path))
-          when "asset"
-            asset_rel = copy_asset(now, command.path, command.lane)
-            base.merge("source" => { "kind" => "asset",
-                                     "label" => command.label || File.basename(command.path) },
-                       "asset" => asset_rel, "body" => nil)
-          end
-        end
-
-        def copy_asset(now, path, lane)
-          date_path = now.strftime("%Y/%m/%d")
-          filename  = File.basename(path)
-          assets_dir = @container.layout.asset_raw_dir(date_path, lane)
-          FileUtils.mkdir_p(assets_dir)
-          FileUtils.cp(path, File.join(assets_dir, filename))
-          sentinel = @container.layout.asset_sentinel_path
-          File.write(sentinel, "*\n") unless File.exist?(sentinel)
-          "raw/#{date_path}/#{lane}/#{filename}"
-        end
-
-        def write_entry(key, structured, mentry, call)
-          writer = Store::Entry::Writer.from(container: @container, call: call)
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Value::Payload.new(meta: nil, body: nil, content: structured))
-        end
-
-        def find_duplicate(index, content_hash, command)
-          dup = index.find_by_hash(content_hash)
-          return dup if dup
-          return unless command.kind == "url"
-
-          index.find_by_url(command.url)
-        end
-
-        def supersede_entry(old_key, new_key, structured, call, store, command)
-          old_mentry = @container.manifest.resolver.resolve(old_key).entry
-          reader = Store::Entry::Reader.from(container: @container)
-          old_env = reader.read(old_key)
-          old_content = old_env&.content || {}
-          tombstone = {}
-          %w[ingested_at].each { |k| tombstone[k] = old_content[k] if old_content.key?(k) }
-          source_kind = old_content.dig("source", "kind")
-          tombstone["source"] = { "kind" => source_kind } if source_kind
-          tombstone["superseded_by"] = new_key
-
-          writer = Store::Entry::Writer.from(container: @container, call: call)
-          writer.put(old_key, mentry: old_mentry,
-                              payload: Textus::Value::Payload.new(meta: nil, body: nil, content: tombstone))
-
-          structured["supersedes"] = old_key
-          env = write_entry(new_key, structured,
-                            @container.manifest.resolver.resolve(new_key).entry, call)
-
-          move_asset(old_content["asset"], command.lane) if command.kind == "asset" && old_content["asset"]
-
-          rebuild_index(store)
-          env
-        end
-
-        def move_asset(old_rel, lane)
-          old_path = @container.layout.asset_resolve(old_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 = @container.layout.asset_raw_dir(date_path, lane)
-          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_rel}: #{e.message}"
-        end
-
-        def rebuild_index(store)
-          Textus::Store::Index::Builder.new(store:).rebuild!(resolver: @container.manifest.resolver)
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/maintenance/jobs_action.rb

@@ -1,21 +0,0 @@
-module Textus
-  module Handlers
-    module Maintenance
-      class JobsAction
-        def initialize(job_store:)
-          @job_store = job_store
-        end
-
-        def call(command, _call)
-          queue = Textus::Store::Jobs::Queue.new(store: @job_store)
-          case command.action
-          when "retry" then queue.retry_failed(command.job_id)
-          when "purge" then queue.purge(command.state)
-          end
-          Value::Result.success("protocol" => Textus::PROTOCOL, "ok" => true,
-                                "state" => command.state, "jobs" => queue.list(command.state))
-        end
-      end
-    end
-  end
-end

data/lib/textus/handlers/maintenance/published_entries.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Handlers
-    module Maintenance
-      class PublishedEntries
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call(_command, _call)
-          Value::Result.success(@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
-end

data/lib/textus/handlers/maintenance/rule_explain.rb

@@ -1,77 +0,0 @@
-module Textus
-  module Handlers
-    module Maintenance
-      class RuleExplain
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call(command, _call)
-          key = command.key
-          result = if command.detail
-                     explain(key)
-                   else
-                     effective(key)
-                   end
-          Value::Result.success(result)
-        end
-
-        LEAN_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY
-                      .select { |_, m| m[:in_rule_explain].include?(:lean) }.keys.freeze
-        DETAIL_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY
-                        .select { |_, m| m[:in_rule_explain].include?(:detail) }.keys.freeze
-        EFFECTIVE_FIELDS = DETAIL_FIELDS.select { |f| Textus::Manifest::Schema::FIELD_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 then retention_hash(value, string_keys: true)
-          when :react then 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::Manifest::Policy::Predicates::FLOOR.keys.to_h do |action|
-              floor = Textus::Manifest::Policy::Predicates::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 then retention_hash(value, string_keys: false)
-          when :react then value.to_h
-          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
-end

data/lib/textus/handlers/maintenance/rule_lint.rb

@@ -1,54 +0,0 @@
-require "yaml"
-
-module Textus
-  module Handlers
-    module Maintenance
-      class RuleLint
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call(command, _call)
-          root = @manifest.data.root
-          live_rules = current_rules(root)
-          candidate_result = parse_candidate(command.candidate_yaml)
-          return candidate_result if candidate_result.is_a?(Value::Result) && candidate_result.failure?
-
-          candidate_rules = candidate_result
-          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
-
-          Value::Result.success(Textus::Store::Jobs::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)
-          return Value::Result.failure(:usage_error, "candidate is not a YAML mapping") unless raw.is_a?(Hash)
-
-          Array(raw["rules"])
-        rescue Psych::Exception => e
-          Value::Result.failure(:usage_error, "candidate YAML parse error: #{e.message}")
-        end
-      end
-    end
-  end
-end