textus 0.53.0 → 0.54.1

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

data/lib/textus/pipeline/acquire/handler.rb

@@ -1,29 +0,0 @@
-require "timeout"
-
-module Textus
-  module Pipeline
-    module Acquire
-      # Invokes a :resolve_handler hook handler by name under a timeout — the single
-      # home for "call the intake handler under a deadline" (ADR 0048 D1). Shared by
-      # Produce::Acquire::Intake (the internal ingest mechanism — no public verb since ADR 0079)
-      # as driven by the converge sweep (drain/serve) and `textus hook run` (ADR 0089 made
-      # ingest system-pushed; there is no read or put trigger).
-      # Always passes a Container as `caps:` so the hook contract (ADR 0027) is
-      # uniform across every entry point. Maps Timeout::Error to a UsageError;
-      # leaves any other error to the caller (call sites differ in how they wrap).
-      module Handler
-        FETCH_TIMEOUT_SECONDS = 30
-
-        module_function
-
-        def invoke(caps:, handler:, config:, args:, label:, timeout: FETCH_TIMEOUT_SECONDS)
-          Timeout.timeout(timeout) do
-            caps.steps.invoke(:fetch, handler, caps: caps, config: config, args: args)
-          end
-        rescue Timeout::Error
-          raise Textus::UsageError.new("#{label} '#{handler}' exceeded #{timeout}s timeout")
-        end
-      end
-    end
-  end
-end

data/lib/textus/pipeline/acquire/intake.rb

@@ -1,132 +0,0 @@
-require "timeout"
-
-module Textus
-  module Pipeline
-    module Acquire
-      # Internal ingest executor for one machine-zone intake entry. No longer a
-      # public verb (ADR 0079 collapsed the `fetch` surface): used by the
-      # converge sweep (drain/serve) and `textus hook run` only — ingest is system-pushed
-      # (ADR 0089 removed the read-through that once also drove it).
-      class Intake
-        FETCH_TIMEOUT_SECONDS = Textus::Pipeline::Acquire::Handler::FETCH_TIMEOUT_SECONDS
-
-        def initialize(container:, call:)
-          @container    = container
-          @call         = call
-          @manifest     = container.manifest
-          @schemas      = container.schemas
-          @steps          = container.steps
-        end
-
-        # call(key) is the primary entry; run is kept as an alias for
-        # Orchestrator and FetchAll which call worker.run(key).
-        def call(key)
-          run(key)
-        end
-
-        def run(key)
-          res = @manifest.resolver.resolve(key)
-          mentry = res.entry
-          path = res.path
-          remaining = res.remaining
-          raise UsageError.new("no intake declared for '#{key}'") unless mentry.intake?
-
-          before_etag = @container.file_store.exists?(path) ? @container.file_store.etag(path) : nil
-          result = fetch_with_events(key, mentry, remaining)
-          persist_and_notify(key, mentry, result, before_etag)
-        end
-
-        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" then { meta: meta_val || {}, body: body.to_s, content: nil }
-          when "text"     then { 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 Textus::UsageError.new("intake for #{format} returned neither content nor body")
-            end
-          else
-            raise Textus::UsageError.new("unknown format #{format.inspect}")
-          end
-        end
-
-        private
-
-        # ADR 0079: a per-rule fetch_timeout_seconds override was an accepted loss
-        # in the fetch:/retention: → lifecycle: collapse; the constant ceiling
-        # applies to every intake.
-        def fetch_timeout_for(_key)
-          FETCH_TIMEOUT_SECONDS
-        end
-
-        def steps_ctx
-          @steps_ctx ||= Textus::Step::Context.for(container: @container, call: @call)
-        end
-
-        def fetch_with_events(key, mentry, remaining)
-          @steps.publish(:entry_fetch_started, ctx: steps_ctx, key: key, mode: :sync)
-          call_intake(key, mentry, remaining)
-        end
-
-        def call_intake(key, mentry, remaining)
-          Textus::Pipeline::Acquire::Handler.invoke(
-            caps: @container, handler: mentry.handler,
-            config: mentry.config,
-            args: { trigger_key: key, leaf_segments: remaining || [] },
-            label: "intake", timeout: fetch_timeout_for(key)
-          )
-        rescue Textus::Error => e
-          @steps.publish(:entry_fetch_failed, ctx: steps_ctx, key: key,
-                                              error_class: e.class.name, error_message: e.message)
-          raise
-        rescue StandardError => e
-          @steps.publish(:entry_fetch_failed, ctx: steps_ctx, key: key,
-                                              error_class: e.class.name, error_message: e.message)
-          raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
-        end
-
-        def persist_and_notify(key, mentry, result, before_etag)
-          normalized = self.class.normalize_action_result(result, format: mentry.format)
-          auth.check_action!(action: :converge, actor: @call.role, key: key)
-          envelope = writer.put(
-            key,
-            mentry: mentry,
-            payload: Textus::Envelope::IO::Writer::Payload.new(
-              meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
-            ),
-          )
-          change = detect_change(before_etag, envelope)
-          unless change == :unchanged
-            @steps.publish(:entry_fetched, ctx: steps_ctx, key: key,
-                                           envelope: envelope, change: change)
-          end
-          envelope
-        end
-
-        def detect_change(before_etag, envelope)
-          if before_etag.nil? then :created
-          elsif envelope.etag == before_etag then :unchanged
-          else :updated
-          end
-        end
-
-        def writer
-          @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
-        end
-
-        def auth
-          @auth ||= Textus::Gate::Auth.new(@container)
-        end
-      end
-    end
-  end
-end