textus 0.8.1 → 0.10.0

data/lib/textus/application/writes/delete.rb

@@ -0,0 +1,36 @@
+module Textus
+  module Application
+    module Writes
+      class Delete
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(key, if_etag: nil, suppress_events: false)
+          @ctx.store.manifest.validate_key!(key)
+          mentry, = @ctx.store.manifest.resolve(key)
+
+          unless @ctx.can_write?(mentry.zone)
+            raise WriteForbidden.new(key, mentry.zone,
+                                     writers: @ctx.store.manifest.zone_writers(mentry.zone))
+          end
+
+          @ctx.store.writer.delete_envelope_from_disk(
+            key, if_etag: if_etag, as: @ctx.role,
+                 correlation_id: @ctx.correlation_id
+          )
+
+          unless suppress_events
+            @bus.publish(:deleted,
+                         store: @ctx.with_role(@ctx.role),
+                         key: key,
+                         correlation_id: @ctx.correlation_id)
+          end
+
+          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/publish.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Application
+    module Writes
+      class Publish
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(source:, target:, key:)
+          Textus::Infra::Publisher.publish(
+            source: source,
+            target: target,
+            store_root: @ctx.store.root,
+          )
+          @bus.publish(:published,
+                       key: key,
+                       source: source,
+                       target: target,
+                       correlation_id: @ctx.correlation_id)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/put.rb

@@ -0,0 +1,43 @@
+module Textus
+  module Application
+    module Writes
+      class Put
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(key, meta: nil, body: nil, content: nil, if_etag: nil, suppress_events: false)
+          @ctx.store.manifest.validate_key!(key)
+          mentry, = @ctx.store.manifest.resolve(key)
+
+          unless @ctx.can_write?(mentry.zone)
+            raise WriteForbidden.new(key, mentry.zone,
+                                     writers: @ctx.store.manifest.zone_writers(mentry.zone))
+          end
+
+          envelope = @ctx.store.writer.write_envelope_to_disk(
+            key,
+            mentry: mentry,
+            meta: meta,
+            body: body,
+            content: content,
+            if_etag: if_etag,
+            as: @ctx.role,
+            correlation_id: @ctx.correlation_id,
+          )
+
+          unless suppress_events
+            @bus.publish(:put,
+                         store: @ctx.with_role(@ctx.role),
+                         key: key,
+                         envelope: envelope,
+                         correlation_id: @ctx.correlation_id)
+          end
+
+          envelope
+        end
+      end
+    end
+  end
+end

data/lib/textus/builder/pipeline.rb

@@ -2,7 +2,7 @@ require "fileutils"
 require "time"
 
 module Textus
-  class Builder
+  module Builder
     module InjectMeta
       # Returns a new hash with _meta as the first key, per SPEC §6 ordering.
       def self.call(content_hash, mentry)

data/lib/textus/builder/renderer/json.rb

@@ -1,7 +1,7 @@
 require "json"
 
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Json < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer/markdown.rb

@@ -1,7 +1,7 @@
 require "time"
 
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Markdown < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer/text.rb

@@ -1,5 +1,5 @@
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Text < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer/yaml.rb

@@ -1,7 +1,7 @@
 require "yaml"
 
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Yaml < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer.rb

@@ -1,5 +1,5 @@
 module Textus
-  class Builder
+  module Builder
     # Abstract base for output renderers. Each concrete renderer owns
     # producing the bytes for one manifest format (markdown/json/yaml/text).
     class Renderer

data/lib/textus/cli/group/policy.rb

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Group
+      class Policy < Group
+        self.cli_name = "policy"
+        subcommands["list"]    = Verb::PolicyList
+        subcommands["explain"] = Verb::PolicyExplain
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/accept.rb

@@ -6,8 +6,8 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(store.accept(key, as: role))
+          ctx = context_for(store)
+          emit(Textus::Composition.writes_accept(ctx).call(key))
         end
       end
     end

data/lib/textus/cli/verb/audit.rb

@@ -0,0 +1,30 @@
+module Textus
+  class CLI
+    class Verb
+      class Audit < Verb
+        option :key_filter, "--key=KEY"
+        option :zone, "--zone=Z"
+        option :role_filter, "--role=ROLE"
+        option :verb_filter, "--verb=V"
+        option :since, "--since=ISO8601|RELATIVE"
+        option :correlation_id, "--correlation-id=ID"
+        option :limit, "--limit=N"
+
+        def call(store)
+          ctx = context_for(store)
+          since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ctx.now)
+          rows = Textus::Composition.audit(ctx).call(
+            key: key_filter,
+            zone: zone,
+            role: role_filter,
+            verb: verb_filter,
+            since: since_time,
+            correlation_id: correlation_id,
+            limit: limit&.to_i,
+          )
+          emit({ "verb" => "audit", "rows" => rows })
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/blame.rb

@@ -0,0 +1,16 @@
+module Textus
+  class CLI
+    class Verb
+      class Blame < Verb
+        option :limit, "--limit=N"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("blame requires a key")
+          ctx = context_for(store)
+          rows = Textus::Composition.blame(ctx).call(key: key, limit: limit&.to_i)
+          emit({ "verb" => "blame", "key" => key, "rows" => rows })
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/build.rb

@@ -5,7 +5,8 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          emit(Textus::Builder.new(store).build(prefix: prefix))
+          ctx = Textus::Composition.context(store, role: "build")
+          emit(Textus::Composition.writes_build(ctx).call(prefix: prefix))
         end
       end
     end

data/lib/textus/cli/verb/delete.rb

@@ -7,8 +7,8 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(store.delete(key, if_etag: if_etag, as: role))
+          ctx = context_for(store)
+          emit(Textus::Composition.writes_delete(ctx).call(key, if_etag: if_etag))
         end
       end
     end

data/lib/textus/cli/verb/freshness.rb

@@ -0,0 +1,16 @@
+module Textus
+  class CLI
+    class Verb
+      class Freshness < Verb
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+
+        def call(store)
+          ctx = context_for(store)
+          rows = Textus::Composition.freshness(ctx).call(prefix: prefix, zone: zone)
+          emit({ "verb" => "freshness", "rows" => rows })
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/get.rb

@@ -2,9 +2,15 @@ module Textus
   class CLI
     class Verb
       class Get < Verb
+        option :as_flag, "--as=ROLE"
+
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          emit(store.get(key))
+          ctx = context_for(store)
+          result = Textus::Composition.reads_get(ctx).call(key)
+          raise Textus::UnknownKey.new(key, suggestions: store.manifest.suggestions_for(key)) if result.nil?
+
+          emit(result)
         end
       end
     end

data/lib/textus/cli/verb/hook_run.rb

@@ -23,16 +23,16 @@ module Textus
           end
 
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          callable = store.registry.rpc_callable(:fetch, name)
-          view = Store::View.new(store, writable: true, as: role)
+          callable = store.registry.rpc_callable(:intake, name)
+          view = Application::Context.new(store: store, role: role)
 
           begin
-            Timeout.timeout(Textus::Refresh::FETCH_TIMEOUT_SECONDS) do
+            Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do
               callable.call(config: {}, store: view, args: args)
             end
           rescue Timeout::Error
             raise UsageError.new(
-              "hook run '#{name}' exceeded #{Textus::Refresh::FETCH_TIMEOUT_SECONDS}s timeout",
+              "hook run '#{name}' exceeded #{Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS}s timeout",
             )
           rescue Textus::Error
             raise

data/lib/textus/cli/verb/mv.rb

@@ -8,8 +8,7 @@ module Textus
         def call(store)
           old_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
           new_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(store.mv(old_key, new_key, as: role, dry_run: dry_run || false))
+          emit(store.mv(old_key, new_key, as: resolved_role(store), dry_run: dry_run || false))
         end
       end
     end

data/lib/textus/cli/verb/policy_explain.rb

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class PolicyExplain < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("policy explain requires a KEY")
+          ctx = context_for(store)
+          result = Textus::Composition.policy_explain(ctx).call(key: key)
+          emit({ "verb" => "policy_explain" }.merge(result.transform_keys(&:to_s)))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/policy_list.rb

@@ -0,0 +1,25 @@
+module Textus
+  class CLI
+    class Verb
+      class PolicyList < Verb
+        def call(store)
+          policies = store.manifest.policies.blocks.map do |b|
+            row = { "match" => b.match }
+            if b.refresh
+              row["refresh"] = {
+                "ttl_seconds" => b.refresh.ttl_seconds,
+                "on_stale" => b.refresh.on_stale,
+                "sync_budget_ms" => b.refresh.sync_budget_ms,
+              }
+            end
+            row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
+            row["promote_requires"] = b.promote.requires if b.promote
+            row["retention"] = b.retention if b.retention
+            row
+          end
+          emit({ "verb" => "policy_list", "policies" => policies })
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/put.rb

@@ -10,20 +10,21 @@ module Textus
           key = positional.shift or raise UsageError.new("put requires a key")
           raise UsageError.new("put requires --stdin in v1") unless use_stdin
 
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+          role = resolved_role(store)
 
           raw = @stdin.read
           payload =
             if fetch_name
-              callable = store.registry.rpc_callable(:fetch, fetch_name)
+              callable = store.registry.rpc_callable(:intake, fetch_name)
               result =
                 begin
-                  Timeout.timeout(Textus::Refresh::FETCH_TIMEOUT_SECONDS) do
-                    callable.call(config: { "bytes" => raw }, store: Textus::Store::View.new(store), args: {})
+                  Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do
+                    callable.call(config: { "bytes" => raw },
+                                  store: Textus::Application::Context.new(store: store, role: role), args: {})
                   end
                 rescue Timeout::Error
                   raise UsageError.new(
-                    "fetch '#{fetch_name}' exceeded #{Textus::Refresh::FETCH_TIMEOUT_SECONDS}s timeout",
+                    "fetch '#{fetch_name}' exceeded #{Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS}s timeout",
                   )
                 end
               basename = key.split(".").last
@@ -32,17 +33,18 @@ module Textus
                   "name" => basename,
                   "last_refreshed_at" => Time.now.utc.iso8601,
                   "fetched_with" => fetch_name,
-                }.merge(result[:_meta] || result["_meta"] || result[:frontmatter] || result["frontmatter"] || {}),
+                }.merge(result[:_meta] || result["_meta"] || {}),
                 "body" => result[:body] || result["body"] || "",
               }
             else
               JSON.parse(raw)
             end
 
-          meta = payload["_meta"] || payload["frontmatter"] || {}
+          meta = payload["_meta"] || {}
           body = payload["body"] || ""
           if_etag = payload["if_etag"]
-          emit(store.put(key, meta: meta, body: body, if_etag: if_etag, as: role))
+          ctx = Textus::Composition.context(store, role: role)
+          emit(Textus::Composition.writes_put(ctx).call(key, meta: meta, body: body, if_etag: if_etag))
         end
       end
     end

data/lib/textus/cli/verb/refresh.rb

@@ -6,8 +6,8 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("refresh requires a key")
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(Textus::Refresh.call(store, key, as: role))
+          ctx = context_for(store)
+          emit(Textus::Composition.refresh_worker(ctx).run(key))
         end
       end
     end

data/lib/textus/cli/verb/refresh_stale.rb

@@ -0,0 +1,18 @@
+module Textus
+  class CLI
+    class Verb
+      class RefreshStale < Verb
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          ctx = context_for(store)
+          result = Textus::Application::Refresh::All.call(ctx, prefix: prefix, zone: zone)
+          emit(result)
+          exit(1) unless result["ok"]
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/reject.rb

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class Reject < Verb
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("reject requires a key")
+          emit(store.reject(key, as: resolved_role(store)))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb.rb

@@ -57,6 +57,20 @@ module Textus
         @stdout.puts(JSON.generate(payload))
         exit_code
       end
+
+      # Resolves the active role for this invocation. Honors the verb's
+      # `--as` flag if declared, then TEXTUS_ROLE, then the project default.
+      def resolved_role(store)
+        flag = respond_to?(:as_flag) ? as_flag : nil
+        Role.resolve(flag: flag, env: ENV, root: store.root)
+      end
+
+      # Returns an Application::Context bound to the resolved role.
+      # Convenience for verbs whose only pre-call boilerplate is
+      # resolving the role and wrapping it in a context.
+      def context_for(store)
+        Textus::Composition.context(store, role: resolved_role(store))
+      end
     end
   end
 end

data/lib/textus/cli.rb

@@ -7,22 +7,27 @@ module Textus
     # plus a new file under lib/textus/cli/.
     VERBS = {
       "accept" => Verb::Accept,
+      "audit" => Verb::Audit,
+      "blame" => Verb::Blame,
+      "reject" => Verb::Reject,
       "build" => Verb::Build,
       "delete" => Verb::Delete,
       "deps" => Verb::Deps,
       "doctor" => Verb::Doctor,
+      "freshness" => Verb::Freshness,
       "get" => Verb::Get,
       "hook" => Group::Hook,
       "init" => Verb::Init,
       "intro" => Verb::Intro,
       "key" => Group::Key,
       "list" => Verb::List,
+      "policy" => Group::Policy,
       "published" => Verb::Published,
       "put" => Verb::Put,
       "rdeps" => Verb::Rdeps,
       "refresh" => Verb::Refresh,
+      "refresh-stale" => Verb::RefreshStale,
       "schema" => Group::Schema,
-      "stale" => Verb::Stale,
       "where" => Verb::Where,
     }.freeze
 
@@ -48,6 +53,10 @@ module Textus
                                   0
       when "--help", "-h"    then print_help
                                   0
+      when "stale"
+        raise UsageError.new(
+          "textus stale was removed in 0.9.2 — use `textus freshness` instead",
+        )
       else
         klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
         dispatch(klass, argv)
@@ -84,13 +93,18 @@ module Textus
           textus where KEY
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
-          textus stale [--prefix=KEY] [--zone=Z]
+          textus freshness [--prefix=KEY] [--zone=Z]
+          textus refresh-stale [--prefix=KEY] [--zone=Z]
+          textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
+          textus blame KEY [--limit=N]
           textus doctor
           textus intro
 
           textus key {mv,uid,migrate}
           textus schema {show,init,diff,migrate}
           textus hook {list,run}
+          textus policy {list,explain}
+          textus migrate {zones,policies}
       HELP
     end
   end

data/lib/textus/composition.rb

@@ -0,0 +1,72 @@
+module Textus
+  module Composition
+    module_function
+
+    def context(store, role:, correlation_id: nil, dry_run: false)
+      Textus::Application::Context.new(
+        store: store,
+        role: role,
+        correlation_id: correlation_id,
+        dry_run: dry_run,
+      )
+    end
+
+    def reads_get(ctx)
+      Textus::Application::Reads::Get.new(ctx: ctx, orchestrator: refresh_orchestrator(ctx))
+    end
+
+    def freshness(ctx)
+      Textus::Application::Reads::Freshness.new(ctx: ctx)
+    end
+
+    def audit(ctx)
+      Textus::Application::Reads::Audit.new(ctx: ctx)
+    end
+
+    def blame(ctx)
+      Textus::Application::Reads::Blame.new(ctx: ctx)
+    end
+
+    def policy_explain(ctx)
+      Textus::Application::Reads::PolicyExplain.new(ctx: ctx)
+    end
+
+    def refresh_worker(ctx)
+      Textus::Application::Refresh::Worker.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def refresh_orchestrator(ctx)
+      Textus::Application::Refresh::Orchestrator.new(
+        worker: refresh_worker(ctx),
+        bus: ctx.store.bus,
+        store_root: ctx.store.root,
+        store: ctx.store,
+        role: ctx.role,
+      )
+    end
+
+    def writes_put(ctx)
+      Textus::Application::Writes::Put.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_delete(ctx)
+      Textus::Application::Writes::Delete.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_build(ctx)
+      Textus::Application::Writes::Build.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_accept(ctx)
+      Textus::Application::Writes::Accept.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_publish(ctx)
+      Textus::Application::Writes::Publish.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def event_bus(ctx)
+      Textus::Infra::EventBus.new(registry: ctx.store.registry)
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module Textus
+  module Doctor
+    class Check
+      # For every entry with an `intake.handler`, look up its handler_allowlist
+      # policy (if any) and verify the declared handler is allowed. Emits a
+      # failure when the handler is rejected by policy.
+      class HandlerAllowlist < Check
+        def call
+          out = []
+          store.manifest.entries.each do |mentry|
+            handler = mentry.intake_handler
+            next if handler.nil?
+
+            allow = store.manifest.policies_for(mentry.key).handler_allowlist
+            next if allow.nil?
+            next if allow.allows?(handler)
+
+            out << {
+              "code" => "policy.handler_not_allowed",
+              "level" => "error",
+              "subject" => mentry.key,
+              "message" => "entry '#{mentry.key}' declares intake.handler='#{handler}' but the " \
+                           "handler_allowlist policy permits only: #{allow.handlers.join(", ")}",
+              "fix" => "either change intake.handler to one of [#{allow.handlers.join(", ")}], " \
+                       "or extend the handler_allowlist policy in .textus/manifest.yaml",
+            }
+          end
+          out
+        end
+      end
+    end
+  end
+end