textus 0.53.0 → 0.54.0

data/lib/textus/background/job.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Background
-    module Job
-      @registry = {}
-
-      def self.registry = @registry
-
-      def self.register(klass)
-        @registry[klass::TYPE] = klass if klass.const_defined?(:TYPE, false)
-      end
-
-      def self.fetch(type)
-        @registry.fetch(type) { raise Textus::UsageError.new("unknown job type: #{type}") }
-      end
-    end
-  end
-end

data/lib/textus/background/planner/plan.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Background
-    module Planner
-      class Plan
-        ACTIONS_BY_TRIGGER = {
-          "convergence" => %w[materialize refresh sweep],
-          "entry.written" => %w[materialize],
-          "entry.deleted" => %w[materialize],
-          "entry.moved" => %w[materialize],
-          "proposal.accepted" => %w[materialize],
-          "proposal.rejected" => %w[materialize],
-        }.freeze
-
-        SCOPE_RESOLVERS = {
-          "materialize" => :producible_keys,
-          "refresh" => :stale_intake_keys,
-          "sweep" => :lane_keys,
-        }.freeze
-
-        def self.seed(container:, queue:, role:)
-          jobs = new(container: container).plan(
-            trigger: { "type" => "convergence" },
-            role: role,
-          )
-          jobs.each { |j| queue.enqueue(j) }
-        end
-
-        def initialize(container:)
-          @container = container
-          @manifest  = container.manifest
-        end
-
-        def plan(trigger:, role:)
-          type = trigger["type"] || trigger[:type]
-          trigger["target"] || trigger[:target]
-          return [] if type.nil?
-
-          blocks_with_react = @manifest.rules.blocks.select(&:react)
-          if blocks_with_react.any?
-            plan_from_rules(blocks_with_react, type, role)
-          else
-            plan_from_defaults(type, role)
-          end
-        end
-
-        private
-
-        def plan_from_rules(blocks, type, role)
-          jobs = []
-          blocks
-            .select { |b| matches_trigger?(b.react, type) }
-            .each do |block|
-              do_action = block.react.raw["do"]
-              Array(do_action).each do |action|
-                if action == "sweep"
-                  jobs << Textus::Ports::Queue::Job.new(
-                    type: "sweep", args: { "scope" => {} }, enqueued_by: role,
-                  )
-                else
-                  resolver = SCOPE_RESOLVERS.fetch(action, :producible_keys)
-                  keys = send(resolver, nil)
-                  keys.each { |key| jobs << job(action, key, role) }
-                end
-              end
-            end
-          jobs
-        end
-
-        def plan_from_defaults(type, role)
-          actions = ACTIONS_BY_TRIGGER.fetch(type, [])
-          jobs = []
-          producible_keys(nil).each { |k| jobs << job("materialize", k, role) } if actions.include?("materialize")
-          stale_intake_keys(nil).each { |k| jobs << job("refresh", k, role) } if actions.include?("refresh")
-          if actions.include?("sweep")
-            jobs << Textus::Ports::Queue::Job.new(
-              type: "sweep", args: { "scope" => {} }, enqueued_by: role,
-            )
-          end
-          jobs
-        end
-
-        def matches_trigger?(react, type)
-          on = react.raw["on"]
-          Array(on).include?(type)
-        end
-
-        def job(type, key, enqueued_by)
-          Textus::Ports::Queue::Job.new(type: type, args: { "key" => key }, enqueued_by: enqueued_by)
-        end
-
-        def producible_keys(_target)
-          @manifest.data.entries
-                   .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
-                   .map(&:key)
-        end
-
-        def stale_intake_keys(_target)
-          Textus::Core::Freshness::Evaluator.new(
-            manifest: @manifest,
-            file_stat: Textus::Ports::Storage::FileStat.new,
-            clock: Textus::Ports::Clock.new,
-          ).stale_intake_keys(prefix: nil, lane: nil)
-        end
-
-        def lane_keys(_target)
-          @manifest.data.entries.map(&:key)
-        end
-      end
-    end
-  end
-end

data/lib/textus/background/retention/apply.rb

@@ -1,50 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Background
-    module Retention
-      class Apply
-        def initialize(container:, call:)
-          @container = container
-          @call = call
-        end
-
-        def call(rows)
-          out = { dropped: [], archived: [], failed: [] }
-          rows.each do |row|
-            key = row["key"]
-            begin
-              case row["action"]
-              when "drop"
-                delete(key)
-                out[:dropped] << key
-              when "archive"
-                archive_leaf(row)
-                delete(key)
-                out[:archived] << key
-              end
-            rescue Textus::Error => e
-              out[:failed] << { "key" => key, "error" => e.message }
-            end
-          end
-          out
-        end
-
-        private
-
-        def archive_leaf(row)
-          src  = row["path"]
-          root = @container.root.to_s
-          rel  = src.delete_prefix("#{root}/")
-          dest = File.join(root, "archive", rel)
-          FileUtils.mkdir_p(File.dirname(dest))
-          FileUtils.cp(src, dest)
-        end
-
-        def delete(key)
-          Textus::Action::KeyDelete.new(key: key).call(container: @container, call: @call)
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/handler_permit.rb

@@ -1,34 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # For every entry with a fetch handler, look up its handler_permit policy
-      # (if any) and verify the declared handler is permitted. Emits a failure
-      # when the handler is rejected by policy.
-      class HandlerPermit < Check
-        def call
-          out = []
-          manifest.data.entries.each do |mentry|
-            next unless mentry.intake?
-
-            handler = mentry.handler
-
-            permit = manifest.rules.for(mentry.key).handler_permit
-            next if permit.nil?
-            next if permit.permits?(handler)
-
-            out << {
-              "code" => "policy.handler_not_permitted",
-              "level" => "error",
-              "subject" => mentry.key,
-              "message" => "entry '#{mentry.key}' declares source.handler='#{handler}' but " \
-                           "handler_permit allows only: #{permit.handlers.join(", ")}",
-              "fix" => "change handler to one of [#{permit.handlers.join(", ")}] or " \
-                       "extend handler_permit in .textus/manifest.yaml",
-            }
-          end
-          out
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/hooks.rb

@@ -1,25 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Hooks < Check
-        def call
-          out = []
-          dir = File.join(root, "steps")
-          return out unless File.directory?(dir)
-
-          Textus::Step::Loader.new(registry: Textus::Step::RegistryStore.new).load_dir(dir)
-          out
-        rescue Textus::UsageError => e
-          out << {
-            "code" => "step.load_failed",
-            "level" => "error",
-            "subject" => "steps",
-            "message" => e.message,
-            "fix" => "open the named step file under .textus/steps/ and fix the error",
-          }
-          out
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/intake_registration.rb

@@ -1,46 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class IntakeRegistration < Check
-        BUILTIN = %i[json csv markdown-links ical-events rss].freeze
-
-        def call
-          declared = collect_declared_handlers
-          registered = steps.names(:fetch).to_set
-
-          out = (declared - registered).map do |name|
-            {
-              "code" => "intake.handler_missing",
-              "level" => "error",
-              "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no fetch step for '#{name}' is registered",
-              "fix" => "create .textus/steps/fetch/#{name}.rb with `class #{name.to_s.split(/[-_]/).map(&:capitalize).join}Fetch < Textus::Step::Fetch`",
-            }
-          end
-
-          (registered - declared - BUILTIN.to_set).each do |name|
-            out << {
-              "code" => "intake.handler_orphan",
-              "level" => "warning",
-              "subject" => name.to_s,
-              "message" => "fetch step '#{name}' is registered but no manifest entry references it",
-              "fix" => "remove the unused step, or add an entry with `intake.handler: #{name}`",
-            }
-          end
-
-          out
-        end
-
-        private
-
-        def collect_declared_handlers
-          set = Set.new
-          manifest.data.entries.each do |mentry|
-            set << mentry.handler.to_sym if mentry.intake?
-          end
-          set
-        end
-      end
-    end
-  end
-end

data/lib/textus/envelope/io/reader.rb

@@ -1,48 +0,0 @@
-module Textus
-  class Envelope
-    module IO
-      # Read-only counterpart to EnvelopeWriter. Resolves a key, reads the
-      # bytes, parses them via the format strategy, and hands back an
-      # Envelope. Used by Mv (pre-move inspection) and by EnvelopeWriter
-      # (existing-uid lookup for the uid-preservation step in #put).
-      #
-      # No audit, no events, no permission checks — those live one layer up.
-      class Reader
-        def self.from(container:)
-          new(file_store: container.file_store, manifest: container.manifest)
-        end
-
-        def initialize(file_store:, manifest:)
-          @file_store = file_store
-          @manifest   = manifest
-        end
-
-        def read(key)
-          res = @manifest.resolver.resolve(key)
-          path = res.path
-          return nil unless @file_store.exists?(path)
-
-          mentry = res.entry
-          raw = @file_store.read(path)
-          parsed = 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: Etag.for_bytes(raw), content: parsed["content"]
-          )
-        end
-
-        def existing_uid(key)
-          env = read(key)
-          env&.uid
-        rescue StandardError
-          nil
-        end
-
-        def exists?(key)
-          @file_store.exists?(@manifest.resolver.resolve(key).path)
-        end
-      end
-    end
-  end
-end

data/lib/textus/envelope/io/writer.rb

@@ -1,211 +0,0 @@
-require "fileutils"
-
-module Textus
-  class Envelope
-    module IO
-      # Owns the write pipeline (validate, serialize, etag-check, write, audit).
-      # Talks to ports (FileStore, Schemas, AuditLog, Manifest) and an
-      # Reader for the existing-uid lookup.
-      #
-      # Invariant: every public method's final action is @audit_log.append(...).
-      #
-      # No permission check, no event firing — those belong to the caller
-      # (Write::Put / ::Delete / ::Mv).
-      class Writer
-        Payload = Data.define(:meta, :body, :content)
-
-        def self.from(container:, call:)
-          new(
-            file_store: container.file_store, manifest: container.manifest,
-            schemas: container.schemas, audit_log: container.audit_log,
-            call: call, reader: Reader.from(container: container)
-          )
-        end
-
-        def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
-          @file_store = file_store
-          @manifest   = manifest
-          @schemas    = schemas
-          @audit_log  = audit_log
-          @call       = call
-          @reader     = reader
-        end
-
-        def put(key, mentry:, payload:, if_etag: nil)
-          path = resolve_path(key)
-          meta, content = prepare_uid(mentry, payload, key)
-          bytes, eff_meta, eff_body, eff_content = serialize_entry(mentry, path, meta, payload, content)
-          enforce_name_match!(path, eff_meta, mentry.format)
-          validate_schema(mentry, eff_meta, eff_content)
-          etag_before = check_etag!(path, key, if_etag)
-          write_bytes(path, bytes)
-          envelope = build_envelope(key, mentry, path, eff_meta, eff_body, eff_content)
-          audit_put(key, etag_before, envelope.etag)
-          envelope
-        end
-
-        def delete(key, mentry: nil, if_etag: nil) # rubocop:disable Lint/UnusedMethodArgument
-          # `mentry:` is accepted for symmetry with `put` / `move` and to
-          # leave room for future format-specific delete hooks; no field
-          # on it is needed today.
-          path = @manifest.resolver.resolve(key).path
-          raise UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)) unless @file_store.exists?(path)
-
-          etag_before = @file_store.etag(path)
-          raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
-
-          @file_store.delete(path)
-          prune_empty_parents(path)
-          @audit_log.append(
-            role: @call.role, verb: "key_delete", key: key,
-            etag_before: etag_before, etag_after: nil,
-            extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
-          )
-        end
-
-        def move(from_key:, to_key:, new_mentry:, if_etag: nil)
-          from_path = @manifest.resolver.resolve(from_key).path
-          to_path   = @manifest.resolver.resolve(to_key).path
-          raise UnknownKey.new(from_key, suggestions: @manifest.resolver.suggestions_for(from_key)) unless @file_store.exists?(from_path)
-
-          etag_before = @file_store.etag(from_path)
-          raise EtagMismatch.new(from_key, if_etag, etag_before) if if_etag && if_etag != etag_before
-
-          FileUtils.mkdir_p(File.dirname(to_path))
-          FileUtils.mv(from_path, to_path)
-          prune_empty_parents(from_path)
-          basename = to_key.split(".").last
-          Entry.for_format(new_mentry.format).rewrite_name(to_path, basename)
-          etag_after = Etag.for_file(to_path)
-
-          raw = @file_store.read(to_path)
-          parsed = Entry.for_format(new_mentry.format).parse(raw, path: to_path)
-          envelope = Textus::Envelope.build(
-            key: to_key, mentry: new_mentry, path: to_path,
-            meta: parsed["_meta"], body: parsed["body"],
-            etag: etag_after, content: parsed["content"]
-          )
-
-          extras = {
-            "from_key" => from_key, "to_key" => to_key,
-            "from_path" => from_path, "to_path" => to_path,
-            "uid" => envelope.uid
-          }
-          extras["correlation_id"] = @call.correlation_id if @call.correlation_id
-
-          @audit_log.append(
-            role: @call.role, verb: "key_mv", key: to_key,
-            etag_before: etag_before, etag_after: etag_after,
-            extras: extras
-          )
-
-          envelope
-        end
-
-        private
-
-        # After a file leaves a directory (delete or move-source), remove any
-        # now-empty parent dirs so bulk move/delete doesn't accrue orphan dirs
-        # (F3 of #161). Floored at the entry's *zone directory* — a zone is a
-        # declared, first-class container, so its own dir is preserved even when
-        # momentarily empty; only the sub-dirs the bulk op carved out are
-        # pruned. Stops at the first non-empty ancestor, so a dir holding a
-        # `.gitkeep` or sibling entries survives. Best-effort: a lost race or a
-        # non-empty dir is silently fine, never fatal to the write.
-        def prune_empty_parents(path)
-          floor = zone_floor(path)
-          return unless floor
-
-          dir = File.dirname(path)
-          while dir.start_with?("#{floor}/") && Dir.empty?(dir)
-            Dir.rmdir(dir)
-            dir = File.dirname(dir)
-          end
-        rescue SystemCallError
-          nil
-        end
-
-        # The zone directory under which `path` lives (`<root>/zones/<zone>`),
-        # or nil if `path` is not under the store's zones tree.
-        def zone_floor(path)
-          zones_root = File.join(@manifest.data.root, "data")
-          prefix = "#{zones_root}/"
-          return nil unless path.start_with?(prefix)
-
-          zone_seg = path.delete_prefix(prefix).split("/").first
-          zone_seg && File.join(zones_root, zone_seg)
-        end
-
-        def ensure_uid(format, meta, content, existing_uid)
-          Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
-        end
-
-        def enforce_name_match!(path, meta, format)
-          Textus::Entry.for_format(format).enforce_name_match!(path, meta)
-        end
-
-        def serialize_for_put(mentry:, path:, meta:, body:, content:)
-          Textus::Entry.for_format(mentry.format).serialize_for_put(
-            meta: meta, body: body, content: content, path: path,
-          )
-        end
-
-        def resolve_path(key)
-          @manifest.resolver.resolve(key).path
-        end
-
-        def prepare_uid(mentry, payload, key)
-          meta = payload.meta || {}
-          existing_uid = @reader.existing_uid(key)
-          ensure_uid(mentry.format, meta, payload.content, existing_uid)
-        end
-
-        def serialize_entry(mentry, path, meta, payload, content)
-          serialize_for_put(
-            mentry: mentry, path: path,
-            meta: meta, body: payload.body, content: content
-          )
-        end
-
-        def validate_schema(mentry, eff_meta, eff_content)
-          schema = @schemas.fetch_or_nil(mentry.schema)
-          return unless schema
-
-          Entry.for_format(mentry.format).validate_against(
-            schema,
-            { "_meta" => eff_meta, "content" => eff_content },
-          )
-        end
-
-        def check_etag!(path, key, if_etag)
-          etag_before = @file_store.exists?(path) ? @file_store.etag(path) : nil
-          raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && (etag_before != if_etag)
-
-          etag_before
-        end
-
-        def write_bytes(path, bytes)
-          @file_store.write(path, bytes)
-        end
-
-        def build_envelope(key, mentry, path, eff_meta, eff_body, eff_content)
-          Textus::Envelope.build(
-            key: key, mentry: mentry, path: path,
-            meta: eff_meta, body: eff_body,
-            etag: Etag.for_bytes(@file_store.read(path)),
-            content: eff_content
-          )
-        end
-
-        def audit_put(key, etag_before, etag_after)
-          extras = @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
-          @audit_log.append(
-            role: @call.role, verb: "put", key: key,
-            etag_before: etag_before, etag_after: etag_after,
-            extras: extras
-          )
-        end
-      end
-    end
-  end
-end

data/lib/textus/events.rb

@@ -1,21 +0,0 @@
-module Textus
-  module Events
-    ENTRY_WRITTEN   = "entry.written"
-    ENTRY_DELETED   = "entry.deleted"
-    ENTRY_RENAMED   = "entry.renamed"
-    ENTRY_FETCHED   = "entry.fetched"
-    ENTRY_DERIVED   = "entry.derived"
-    ENTRY_VALIDATED = "entry.validated"
-    ENTRY_PUBLISHED = "entry.published"
-    PIPELINE_FAILED = "pipeline.failed"
-
-    STEP_FETCH_COMPLETE     = "step.fetch.complete"
-    STEP_TRANSFORM_COMPLETE = "step.transform.complete"
-    STEP_VALIDATE_PASSED    = "step.validate.passed"
-    STEP_VALIDATE_FAILED    = "step.validate.failed"
-
-    STORE_LOADED   = "store.loaded"
-    SESSION_OPENED = "session.opened"
-    SESSION_CLOSED = "session.closed"
-  end
-end

data/lib/textus/init/templates/machine_intake.rb

@@ -1,49 +0,0 @@
-# .textus/steps/fetch/machine_intake.rb
-# Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
-# entry from manifest.yaml if you don't want it.
-# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus drain`
-# (never on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
-# `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
-# (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
-# ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
-module Textus
-  module Step
-    class MachineIntakeFetch < Fetch
-      def call(config:, args:, caps:, **)
-        machine = args[:leaf_segments].first or
-          raise "machines intake needs a host leaf, e.g. the 'local' in feeds.machines.local"
-        spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
-        unless (spec["via"] || "local").to_s == "local"
-          raise "machine #{machine}: only `via: local` is scaffolded — see " \
-                "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
-        end
-
-        sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
-        ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
-        count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
-        { content: {
-          # git_* describe THIS repo on the control host — only meaningful for `local`.
-          "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
-          "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
-          "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
-          "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
-          "captured_at"    => Time.now.utc.iso8601,
-          "os"             => RbConfig::CONFIG["host_os"],
-          "arch"           => RbConfig::CONFIG["host_cpu"],
-          "ruby_version"   => RUBY_VERSION,
-          "runtimes"       => {                                 # versions only; nil when not installed
-            "node"   => ver.call("node --version"),
-            "python" => ver.call("python3 --version"),
-            "go"     => ver.call("go version"),
-          },
-          "packages"       => {                                 # COUNTS only — never the list (size/secrets)
-            "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
-            "apt"  => count.call("dpkg-query -f '.\n' -W"),
-          },
-          "textus_version" => Textus::VERSION,
-          "protocol"       => Textus::PROTOCOL,
-        } }
-      end
-    end
-  end
-end

data/lib/textus/init/templates/orientation_reducer.rb

@@ -1,21 +0,0 @@
-# Reducer that reshapes the raw projection rows into the keys the
-# orientation.mustache template references. Without this, the template
-# would only have access to the flat rows list.
-module Textus
-  module Step
-    class OrientationTransform < Transform
-      def call(rows:, config:, **)
-        project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
-        runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
-
-        {
-          "project" => {
-            "name" => project_row["name"],
-            "description" => project_row["description"]
-          },
-          "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
-        }
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/validators/events.rb

@@ -1,22 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module Events
-          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            pubsub_events = Textus::Step::Catalog::PUBSUB.keys
-            events = entry.events
-            events.each_key do |evt|
-              next if pubsub_events.include?(evt.to_sym)
-
-              raise UsageError.new(
-                "entry '#{entry.key}': unknown event '#{evt}' in events: block. " \
-                "Known events: #{pubsub_events.join(", ")}.",
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/handler_permit.rb

@@ -1,17 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      class HandlerPermit
-        attr_reader :handlers
-
-        def initialize(handlers:)
-          @handlers = Array(handlers).map(&:to_s).freeze
-        end
-
-        def permits?(handler)
-          @handlers.include?(handler.to_s)
-        end
-      end
-    end
-  end
-end