textus 0.18.0 → 0.20.2

data/lib/textus/dependencies.rb

@@ -1,23 +0,0 @@
-module Textus
-  module Dependencies
-    def self.deps_of(manifest, key)
-      entry = manifest.entries.find { |e| e.key == key } or return []
-      result = Array(entry.projection&.fetch("select", nil)).map { |s| s }
-      Array(entry.generator&.fetch("sources", nil)).each { |s| result << s }
-      result.uniq
-    end
-
-    def self.rdeps_of(manifest, key)
-      manifest.entries.each_with_object([]) do |e, acc|
-        sources = Array(e.projection&.fetch("select", nil)) + Array(e.generator&.fetch("sources", nil))
-        acc << e.key if sources.any? { |s| s == key || key.start_with?("#{s}.") }
-      end
-    end
-
-    def self.published_of(manifest)
-      manifest.entries.reject { |e| e.publish_to.empty? }.map do |e|
-        { "key" => e.key, "publish_to" => e.publish_to }
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/human_accept.rb

@@ -1,31 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        class HumanAccept
-          attr_reader :reason
-
-          def name
-            "human_accept"
-          end
-
-          # The role is passed via `store` (an Application::Context-like object
-          # with a `role` reader) or through the entry metadata. In practice,
-          # Accept already enforces role == "human" before reaching the
-          # promotion gate, so this predicate trivially passes. It documents
-          # intent and future-proofs multi-actor accept flows.
-          def call(store:, entry: nil) # rubocop:disable Lint/UnusedMethodArgument
-            role = store.respond_to?(:role) ? store.role.to_s : nil
-            # If we cannot determine the role (e.g. store doesn't expose it),
-            # we trust that Accept has already checked — allow through.
-            return true if role.nil?
-
-            ok = (role == "human")
-            @reason = "current role is '#{role}', expected 'human'" unless ok
-            ok
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy.rb

@@ -1,7 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      ALLOWED_ON_STALE = %i[warn sync timed_sync].freeze
-    end
-  end
-end

data/lib/textus/hooks/dispatcher.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Textus
-  module Hooks
-    class Dispatcher
-      HOOK_TIMEOUT_SECONDS = 2
-
-      def initialize
-        @subscribers = Hash.new { |h, k| h[k] = [] }
-        @error_handlers = []
-      end
-
-      # Register an error callback invoked when a user hook raises.
-      # Used by Infra::AuditSubscriber to record an "event_error" audit row.
-      def on_error(&block)
-        @error_handlers << block
-      end
-
-      def subscribe(event, name, keys: nil, &block)
-        @subscribers[event.to_sym] << { name: name.to_sym, callable: block, keys: keys }
-      end
-
-      def publish(event, **kwargs)
-        key = kwargs[:key] || "-"
-        @subscribers[event.to_sym].each do |sub|
-          next unless match?(sub[:keys], key)
-
-          invoke(event, sub, key, kwargs)
-        end
-      end
-
-      private
-
-      def invoke(event, sub, key, kwargs)
-        accepted = filter_kwargs(sub[:callable], kwargs)
-        Timeout.timeout(HOOK_TIMEOUT_SECONDS) { sub[:callable].call(**accepted) }
-      rescue StandardError => e
-        notify_error(event, sub, key, kwargs, e)
-      end
-
-      def notify_error(event, sub, key, kwargs, error)
-        @error_handlers.each do |handler|
-          handler.call(event: event, hook: sub[:name], key: key, kwargs: kwargs, error: error)
-        rescue StandardError => e
-          warn "[textus] error handler failed: #{e.class}: #{e.message}"
-        end
-      end
-
-      # Passes only the kwargs a hook block declares. Lets us extend event
-      # payloads (e.g., correlation_id) without breaking hooks written against
-      # the old signature.
-      def filter_kwargs(callable, kwargs)
-        params = callable.parameters
-        return kwargs if params.any? { |type, _| type == :keyrest }
-
-        accepted = params.each_with_object([]) do |(type, name), acc|
-          acc << name if %i[key keyreq].include?(type)
-        end
-        kwargs.slice(*accepted)
-      end
-
-      def match?(globs, key)
-        return true if globs.nil?
-
-        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
-      end
-    end
-  end
-end

data/lib/textus/hooks/registry.rb

@@ -1,85 +0,0 @@
-module Textus
-  module Hooks
-    class Registry
-      EVENTS = {
-        # RPC: exactly 1 handler per name; return value flows into store; failure aborts.
-        resolve_intake: { mode: :rpc, args: %i[store config args] },
-        transform_rows: { mode: :rpc, args: %i[store rows config] },
-        validate: { mode: :rpc, args: %i[store] },
-
-        # Pub-sub: 0..N handlers per event; return discarded; failure logged to audit.
-        entry_put: { mode: :pubsub, args: %i[store key envelope] },
-        entry_deleted: { mode: :pubsub, args: %i[store key] },
-        entry_refreshed: { mode: :pubsub, args: %i[store key envelope change] },
-        entry_renamed: { mode: :pubsub, args: %i[store key from_key to_key envelope] },
-        build_completed: { mode: :pubsub, args: %i[store key envelope sources] },
-        proposal_accepted: { mode: :pubsub, args: %i[store key target_key] },
-        proposal_rejected: { mode: :pubsub, args: %i[store key target_key] },
-        file_published: { mode: :pubsub, args: %i[store key envelope source target] },
-        store_loaded: { mode: :pubsub, args: %i[store] },
-        refresh_started: { mode: :pubsub, args: %i[store key mode] },
-        refresh_failed: { mode: :pubsub, args: %i[store key error_class error_message] },
-        refresh_backgrounded: { mode: :pubsub, args: %i[store key started_at budget_ms] },
-      }.freeze
-
-      def initialize(dispatcher: nil)
-        @rpc        = Hash.new { |h, k| h[k] = {} }   # event => { name => callable }
-        @pubsub     = Hash.new { |h, k| h[k] = [] }   # event => [{name:, callable:, keys:}]
-        @dispatcher = dispatcher
-      end
-
-      def on(event, name, keys: nil, &)
-        register(event, name, keys: keys, &)
-      end
-
-      def register(event, name, keys: nil, &blk)
-        event_sym = event.to_sym
-        spec = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
-        shape_check!(event_sym, spec, blk)
-        name = name.to_sym
-
-        case spec[:mode]
-        when :rpc
-          raise UsageError.new("#{event_sym} '#{name}' already registered") if @rpc[event_sym].key?(name)
-
-          @rpc[event_sym][name] = blk
-        when :pubsub
-          raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
-
-          @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
-          @dispatcher&.subscribe(event_sym, name, keys: keys, &blk)
-        end
-      end
-
-      def rpc_callable(event, name)
-        @rpc[event.to_sym][name.to_sym] or
-          raise UsageError.new("unknown #{event}: #{name}")
-      end
-
-      def listeners(event, key:)
-        @pubsub[event.to_sym].select { |h| h[:keys].nil? || matches_any?(h[:keys], key) }
-      end
-
-      def rpc_names(event) = @rpc[event.to_sym].keys
-      def pubsub_handlers(event) = @pubsub[event.to_sym]
-
-      private
-
-      def shape_check!(event, spec, blk)
-        required = spec[:args]
-        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        keyrest  = provided.any? { |t, _| t == :keyrest }
-        missing  = required - provided.map { |_, n| n }
-        return if keyrest || missing.empty?
-
-        raise UsageError.new(
-          "#{event} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})",
-        )
-      end
-
-      def matches_any?(globs, key)
-        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
-      end
-    end
-  end
-end

data/lib/textus/manifest/resolution.rb

@@ -1,5 +0,0 @@
-module Textus
-  class Manifest
-    Resolution = Data.define(:entry, :path, :remaining)
-  end
-end

data/lib/textus/migrate_keys.rb

@@ -1,187 +0,0 @@
-module Textus
-  # Run-once helper that renames files/directories whose basenames don't
-  # conform to the strict key grammar (§3 of plan-1.2). Only walks
-  # nested: true manifest entries — leaf entries with illegal declared
-  # keys are caught by Manifest load and must be fixed by hand.
-  module MigrateKeys
-    SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
-
-    module_function
-
-    # Returns the envelope hash described in plan-1.2 §3.
-    def run(store, write: false)
-      plan = build_plan(store)
-      collisions = plan[:collisions]
-      renames = plan[:renames]
-
-      ok = collisions.empty?
-      apply!(store, renames) if write && ok
-
-      {
-        "protocol" => Textus::PROTOCOL,
-        "mode" => write ? "write" : "dry-run",
-        "renames" => renames.map { |r| envelope_rename(r) },
-        "collisions" => collisions.map { |c| envelope_collision(c) },
-        "ok" => ok,
-      }
-    end
-
-    # ------------------------------------------------------------------
-    # Plan construction
-    # ------------------------------------------------------------------
-
-    # Returns { renames: [...], collisions: [...] }
-    # Each rename: { from:, to:, old_key:, new_key:, kind: :file|:dir }
-    # Each collision: { target:, sources: [...] }
-    def build_plan(store) # rubocop:disable Metrics/AbcSize
-      renames = []
-      target_buckets = Hash.new { |h, k| h[k] = [] } # target_path => [source_path, ...]
-
-      store.manifest.entries.each do |entry|
-        next unless entry.nested
-
-        base = File.join(store.root, "zones", entry.path)
-        next unless File.directory?(base)
-
-        # Walk depth-first. Order matters when computing the "new key"
-        # for files inside a renamed directory: we record renames bottom-up,
-        # so children are renamed before their parents on apply.
-        walk(base) do |abs_path, is_dir|
-          next if abs_path == base
-
-          basename = File.basename(abs_path)
-          stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-          next if stem.match?(SEGMENT)
-
-          new_stem = normalize(stem)
-          # Skip if normalization yields the same stem (e.g. already-legal
-          # under a different lens). In practice match?(SEGMENT) catches that
-          # above; this is a safety net.
-          next if new_stem == stem
-
-          new_basename = is_dir ? new_stem : new_stem + File.extname(basename)
-          target = File.join(File.dirname(abs_path), new_basename)
-          target_buckets[target] << abs_path
-
-          renames << {
-            from: abs_path,
-            to: target,
-            kind: is_dir ? :dir : :file,
-            entry: entry,
-            base: base,
-          }
-        end
-      end
-
-      collisions = target_buckets.select { |_, srcs| srcs.length > 1 }
-                                 .map { |t, srcs| { target: t, sources: srcs.sort } }
-
-      # Drop colliding entries from renames (we won't apply any of them)
-      colliding_targets = collisions.to_set { |c| c[:target] }
-      renames.reject! { |r| colliding_targets.include?(r[:to]) }
-
-      # Sort renames bottom-up (deepest path first) so children move before parents.
-      renames.sort_by! { |r| -r[:from].count("/") }
-
-      { renames: renames, collisions: collisions }
-    end
-
-    # Yields [absolute_path, is_dir] for every entry under root. Depth-first.
-    def walk(root, &block)
-      Dir.each_child(root) do |name|
-        abs = File.join(root, name)
-        if File.directory?(abs)
-          walk(abs, &block)
-          yield abs, true
-        else
-          yield abs, false
-        end
-      end
-    end
-
-    # Deterministic transform per plan §3.
-    def normalize(s)
-      s = s.downcase
-      s = s.gsub(/[^a-z0-9-]/, "-") # ., _, and anything else become -
-      s = s.gsub(/-+/, "-")
-      s.sub(/\A-+/, "").sub(/-+\z/, "")
-    end
-
-    # ------------------------------------------------------------------
-    # Apply
-    # ------------------------------------------------------------------
-
-    def apply!(store, renames)
-      audit = Textus::Infra::AuditLog.new(store.root)
-      renames.each do |r|
-        # Bottom-up order means a child's ancestors haven't moved yet, so
-        # `from`/`to` are valid as-recorded. The audit `key` reflects the
-        # eventual full key once every rename in this batch has applied.
-        from = r[:from]
-        to = r[:to]
-        File.rename(from, to)
-        new_key = compute_new_key(r, renames)
-        audit.append(
-          role: "runner",
-          verb: "migrate-keys",
-          key: new_key,
-          etag_before: nil,
-          etag_after: nil,
-          extras: { "from" => from, "to" => to },
-        )
-      end
-    end
-
-    # If an ancestor of `path` was renamed earlier in this batch, rewrite the path.
-    def resolve_current_path(path, renames)
-      out = path
-      renames.each do |r|
-        prefix = r[:from] + "/"
-        out = r[:to] + out[r[:from].length..] if out.start_with?(prefix)
-      end
-      out
-    end
-
-    # New full key after applying all renames up through this one.
-    def compute_new_key(rename, renames)
-      base = rename[:base]
-      entry = rename[:entry]
-      new_to = resolve_current_path(rename[:to], renames)
-
-      rel = new_to.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-      stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "") unless rename[:kind] == :dir
-      stripped ||= rel
-      segs = stripped.split("/").reject(&:empty?)
-      (entry.key.split(".") + segs).join(".")
-    end
-
-    # ------------------------------------------------------------------
-    # Envelope helpers
-    # ------------------------------------------------------------------
-
-    def envelope_rename(r)
-      {
-        "from" => r[:from],
-        "to" => r[:to],
-        "old_key" => path_to_key(r[:from], r[:base], r[:entry], r[:kind]),
-        "new_key" => path_to_key(r[:to], r[:base], r[:entry], r[:kind]),
-      }
-    end
-
-    def envelope_collision(col)
-      { "target" => col[:target], "sources" => col[:sources] }
-    end
-
-    def path_to_key(path, base, entry, kind)
-      rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-      stripped =
-        if kind == :dir
-          rel
-        else
-          rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
-        end
-      segs = stripped.split("/").reject(&:empty?)
-      (entry.key.split(".") + segs).join(".")
-    end
-  end
-end

data/lib/textus/projection.rb

@@ -1,89 +0,0 @@
-require "time"
-require "timeout"
-
-module Textus
-  class Projection
-    MAX_LIMIT = 1000
-    REDUCER_TIMEOUT_SECONDS = 2
-
-    # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
-    #   semantics: pure read (`ops.get`) for materialization paths;
-    #   `ops.get_or_refresh` if you want refresh-on-stale.
-    # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
-    # `transform_resolver` — a callable `->(name) { callable_or_raise }`.
-    # `transform_context` — `Application::Context` handed to the transform reducer.
-    def initialize(reader:, spec:, lister:, transform_resolver:, transform_context:)
-      @reader             = reader
-      @spec               = spec || {}
-      @lister             = lister
-      @transform_resolver = transform_resolver
-      @transform_context  = transform_context
-      @limit = (@spec["limit"] || MAX_LIMIT).to_i
-      raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
-    end
-
-    def run
-      keys = collect_keys
-      explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
-      rows = keys.map do |key|
-        env = @reader.call(key)
-        row = pluck(env.meta, env.body)
-        explicit_pluck ? row : row.merge("_key" => key)
-      end
-      reduced = apply_reducer(rows)
-      # Reducers may return either an Array of rows (legacy / templated builds)
-      # or a Hash that becomes the structured-format payload base. In the Hash
-      # case, downstream sort/limit/position markers don't apply, and the
-      # builder owns `_meta.generated_at` so we don't stamp it here.
-      return reduced if reduced.is_a?(Hash)
-
-      rows = reduced
-      rows = sort(rows)
-      rows = rows.first(@limit)
-      mark_positions(rows)
-      { "entries" => rows, "count" => rows.length, "generated_at" => Time.now.utc.iso8601 }
-    end
-
-    private
-
-    def apply_reducer(rows)
-      name = @spec["transform"] or return rows
-      callable = @transform_resolver.call(name)
-      Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
-        callable.call(store: @transform_context, rows: rows, config: @spec["transform_config"] || {})
-      end
-    rescue Timeout::Error
-      raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
-    end
-
-    def collect_keys
-      prefixes = Array(@spec["select"])
-      prefixes.flat_map { |p| @lister.call(prefix: p).map { |row| row["key"] } }.uniq
-    end
-
-    def pluck(frontmatter, _body)
-      fields = @spec["pluck"]
-      if fields.nil? || fields == "*"
-        frontmatter
-      else
-        Array(fields).each_with_object({}) { |f, h| h[f] = frontmatter[f] if frontmatter.key?(f) }
-      end
-    end
-
-    # Adds `_first`, `_last`, and `_index` markers so templates can emit
-    # delimiters (e.g. JSON commas) via {{^_last}},{{/_last}}.
-    def mark_positions(rows)
-      last_idx = rows.length - 1
-      rows.each_with_index do |row, i|
-        row["_index"] = i
-        row["_first"] = i.zero?
-        row["_last"]  = (i == last_idx)
-      end
-    end
-
-    def sort(rows)
-      sb = @spec["sort_by"] or return rows
-      rows.sort_by { |r| r[sb].to_s }
-    end
-  end
-end

data/lib/textus/refresh.rb

@@ -1,39 +0,0 @@
-module Textus
-  module Refresh
-    def self.call(store, key, as:)
-      Textus::Operations.for(store, role: as).refresh(key)
-    end
-
-    def self.refresh_stale(store, prefix: nil, zone: nil, as: "runner")
-      ops = Textus::Operations.for(store, role: as)
-      Textus::Application::Refresh::All.call(ops.ctx, prefix: prefix, zone: zone)
-    end
-
-    # Normalize the three accepted intake return shapes into the store's
-    # internal {frontmatter, body, content} representation.
-    def self.normalize_action_result(res, format:)
-      res = res.transform_keys(&:to_s) if res.is_a?(Hash)
-      res ||= {}
-      meta_val = res["_meta"]
-      body    = res["body"]
-      content = res["content"]
-
-      case format
-      when "markdown"
-        { meta: meta_val || {}, body: body.to_s, content: nil }
-      when "text"
-        { meta: {}, body: body.to_s, content: nil }
-      when "json", "yaml"
-        if !content.nil?
-          { meta: meta_val || {}, body: nil, content: content }
-        elsif !body.nil?
-          { meta: {}, body: body.to_s, content: nil }
-        else
-          raise UsageError.new("intake for #{format} returned neither content nor body")
-        end
-      else
-        raise UsageError.new("unknown format #{format.inspect}")
-      end
-    end
-  end
-end