textus 0.12.1 → 0.14.0

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

@@ -0,0 +1,45 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module IndexFilename
+          def self.call(entry)
+            return if entry.index_filename.nil?
+
+            check_shape!(entry)
+            check_extension!(entry)
+          end
+
+          def self.check_shape!(entry)
+            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested
+
+            unless entry.index_filename.is_a?(String) && !entry.index_filename.empty?
+              raise UsageError.new("entry '#{entry.key}': index_filename must be a non-empty string")
+            end
+
+            return unless entry.index_filename.include?("/") || File.basename(entry.index_filename) != entry.index_filename
+
+            raise UsageError.new("entry '#{entry.key}': index_filename must be a bare basename (no slashes)")
+          end
+
+          def self.check_extension!(entry)
+            ext = File.extname(entry.index_filename)
+            inferred = Textus::Entry.infer_from_extension(ext)
+
+            if inferred.nil?
+              raise UsageError.new(
+                "entry '#{entry.key}': index_filename #{entry.index_filename.inspect} has unknown extension #{ext.inspect}",
+              )
+            end
+            return if inferred == entry.format
+
+            raise UsageError.new(
+              "entry '#{entry.key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
+              "but entry format is #{entry.format.inspect}",
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module InjectIntro
+          def self.call(entry)
+            return unless entry.inject_intro
+
+            raise UsageError.new("entry '#{entry.key}': inject_intro: is only valid on derived entries") unless entry.in_generator_zone?
+            return unless entry.template.nil?
+
+            raise UsageError.new("entry '#{entry.key}': inject_intro: requires a template:")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module PublishEach
+          KNOWN_VARS = %w[leaf basename key ext].freeze
+          VAR_RE = /\{([a-z]+)\}/
+          REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
+
+          def self.call(entry)
+            return if entry.publish_each.nil?
+
+            raise UsageError.new("entry '#{entry.key}': publish_each requires nested: true") unless entry.nested
+            raise UsageError.new("entry '#{entry.key}': publish_to and publish_each are mutually exclusive") unless entry.publish_to.empty?
+            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless entry.publish_each.is_a?(String)
+
+            used_vars = entry.publish_each.scan(VAR_RE).flatten
+            unknown = used_vars - KNOWN_VARS
+            unless unknown.empty?
+              raise UsageError.new(
+                "entry '#{entry.key}': publish_each uses unknown template variable(s) " \
+                "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{KNOWN_VARS.map { |v| "{#{v}}" }.join(", ")}.",
+              )
+            end
+
+            return if used_vars.any? { |v| REQUIRED_DISCRIMINATOR_VARS.include?(v) }
+
+            raise UsageError.new(
+              "entry '#{entry.key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
+              "(else every leaf would clobber the same target).",
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        REGISTERED = [
+          Events,
+          PublishEach,
+          InjectIntro,
+          IndexFilename,
+          FormatMatrix,
+        ].freeze
+
+        def self.run_all(entry)
+          REGISTERED.each { |v| v.call(entry) }
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry.rb

@@ -1,41 +1,44 @@
 module Textus
   class Manifest
     class Entry
-      PUBLISH_EACH_VARS = %w[leaf basename key ext].freeze
-      PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
-
-      COMPUTE_KINDS = %w[projection external].freeze
-
-      attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
-                  :projection, :template, :publish_to, :publish_each,
-                  :intake_handler, :intake_config,
-                  :events, :inject_intro, :index_filename, :compute
-
-      def initialize(manifest, raw)
+      # Re-exported for backward compatibility with callers that referenced these
+      # constants on Entry. Canonical source is the PublishEach validator.
+      PUBLISH_EACH_VARS = Validators::PublishEach::KNOWN_VARS
+      PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
+
+      attr_reader :raw, :key, :path, :zone, :schema, :owner, :nested,
+                  :template, :publish_to, :publish_each,
+                  :events, :inject_intro, :index_filename, :format,
+                  :compute, :projection, :generator,
+                  :intake_handler, :intake_config
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, nested:,
+                     template:, publish_to:, publish_each:, events:, inject_intro:,
+                     index_filename:, format:, compute:, projection:, generator:,
+                     intake_handler:, intake_config:)
         @manifest = manifest
         @raw = raw
-        @key = raw["key"] or raise UsageError.new("manifest entry missing key")
-        @path = raw["path"] or raise UsageError.new("manifest entry '#{@key}' missing path")
-        @zone = raw["zone"] or raise UsageError.new("manifest entry '#{@key}' missing zone")
-        @schema = raw["schema"]
-        @owner = raw["owner"]
-        @nested = raw["nested"] == true
-        parse_compute!(raw)
-        @template = raw["template"]
-        @publish_to = Array(raw["publish_to"])
-        @publish_each = raw["publish_each"]
-        @events = raw["events"] || {}
-        @inject_intro = raw["inject_intro"] == true
-        @index_filename = raw["index_filename"]
-        @format = resolve_format!(raw["format"])
-
-        validate_events!
-        parse_intake!(raw["intake"])
-        validate_format_matrix!
-        validate_publish_each!
-        validate_inject_intro!
-        validate_index_filename!
+        @key = key
+        @path = path
+        @zone = zone
+        @schema = schema
+        @owner = owner
+        @nested = nested
+        @template = template
+        @publish_to = publish_to
+        @publish_each = publish_each
+        @events = events
+        @inject_intro = inject_intro
+        @index_filename = index_filename
+        @format = format
+        @compute = compute
+        @projection = projection
+        @generator = generator
+        @intake_handler = intake_handler
+        @intake_config = intake_config
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Resolves the per-leaf target path (relative to repo root) for a full
       # dotted key under this entry's prefix. Returns nil if this entry has no
@@ -69,192 +72,11 @@ module Textus
 
       private
 
-      # `index_filename:` makes a nested entry treat a fixed basename (e.g.
-      # `SKILL.md`) as the per-directory row. The directory path becomes the
-      # key suffix; sibling files are not enumerated. Allows projecting
-      # spec-mandated filenames that would otherwise be rejected by the
-      # lowercase-only key segment grammar.
-      def validate_index_filename!
-        return if @index_filename.nil?
-
-        raise UsageError.new("entry '#{@key}': index_filename requires nested: true") unless @nested
-        unless @index_filename.is_a?(String) && !@index_filename.empty?
-          raise UsageError.new("entry '#{@key}': index_filename must be a non-empty string")
-        end
-        if @index_filename.include?("/") || File.basename(@index_filename) != @index_filename
-          raise UsageError.new("entry '#{@key}': index_filename must be a bare basename (no slashes)")
-        end
-
-        ext = File.extname(@index_filename)
-        inferred = Manifest::EXT_TO_FORMAT[ext]
-        if inferred.nil?
-          raise UsageError.new(
-            "entry '#{@key}': index_filename #{@index_filename.inspect} has unknown extension #{ext.inspect}",
-          )
-        end
-        return if inferred == @format
-
-        raise UsageError.new(
-          "entry '#{@key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
-          "but entry format is #{@format.inspect}",
-        )
-      end
-
       def zone_writers
         @manifest.zone_writers(@zone)
       rescue UsageError => e
         raise UsageError.new("entry '#{@key}': #{e.message}")
       end
-
-      def validate_inject_intro!
-        return unless @inject_intro
-
-        unless in_generator_zone?
-          raise UsageError.new(
-            "entry '#{@key}': inject_intro: is only valid on derived entries",
-          )
-        end
-        return unless @template.nil?
-
-        raise UsageError.new(
-          "entry '#{@key}': inject_intro: requires a template:",
-        )
-      end
-
-      def validate_publish_each!
-        return if @publish_each.nil?
-
-        raise UsageError.new("entry '#{@key}': publish_each requires nested: true") unless @nested
-        raise UsageError.new("entry '#{@key}': publish_to and publish_each are mutually exclusive") unless @publish_to.empty?
-        raise UsageError.new("entry '#{@key}': publish_each must be a string") unless @publish_each.is_a?(String)
-
-        used_vars = @publish_each.scan(PUBLISH_EACH_VAR_RE).flatten
-        unknown = used_vars - PUBLISH_EACH_VARS
-        unless unknown.empty?
-          raise UsageError.new(
-            "entry '#{@key}': publish_each uses unknown template variable(s) " \
-            "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{PUBLISH_EACH_VARS.map { |v| "{#{v}}" }.join(", ")}.",
-          )
-        end
-
-        required = %w[leaf basename key]
-        return if used_vars.any? { |v| required.include?(v) }
-
-        raise UsageError.new(
-          "entry '#{@key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
-          "(else every leaf would clobber the same target).",
-        )
-      end
-
-      def resolve_format!(declared)
-        ext = File.extname(@path)
-        inferred = Manifest::EXT_TO_FORMAT[ext]
-
-        if declared.nil?
-          return inferred if inferred
-          # No extension: nested defaults to markdown, leaf with no ext also markdown.
-          return "markdown" if ext == "" && @nested
-          return "markdown" if ext == ""
-        else
-          unless Manifest::EXT_TO_FORMAT.values.include?(declared)
-            raise UsageError.new("entry '#{@key}': unknown format #{declared.inspect}")
-          end
-          # If the path has an extension, the declared format must match.
-          if ext != "" && inferred && inferred != declared
-            raise UsageError.new(
-              "entry '#{@key}': path extension #{ext.inspect} does not match declared format #{declared.inspect}",
-            )
-          end
-          return declared
-        end
-
-        "markdown"
-      end
-
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      def validate_format_matrix!
-        ext = File.extname(@path)
-
-        case @format
-        when "markdown"
-          # .md, or no extension (will be appended). Anything else is a mismatch caught above.
-          raise UsageError.new("entry '#{@key}': markdown format requires '.md' path (got #{ext.inspect})") if ext != "" && ext != ".md"
-        when "json"
-          if @nested
-            # nested json: path is a directory; ext must be empty.
-            raise UsageError.new("entry '#{@key}': nested json path must not have an extension") if ext != ""
-          elsif ext != ".json"
-            raise UsageError.new("entry '#{@key}': json format requires '.json' path (got #{ext.inspect})")
-          end
-        when "yaml"
-          if @nested
-            raise UsageError.new("entry '#{@key}': nested yaml path must not have an extension") if ext != ""
-          elsif ext != ".yaml" && ext != ".yml"
-            raise UsageError.new("entry '#{@key}': yaml format requires '.yaml' or '.yml' path (got #{ext.inspect})")
-          end
-        when "text"
-          if @nested
-            raise UsageError.new("entry '#{@key}': nested text path must not have an extension") if ext != ""
-          elsif ext != ".txt" && ext != ""
-            raise UsageError.new("entry '#{@key}': text format requires '.txt' or no extension (got #{ext.inspect})")
-          end
-        end
-
-        # Schema rules.
-        raise UsageError.new("entry '#{@key}': text format must not declare a schema") if @format == "text" && !@schema.nil?
-
-        # Template-required-for-derived rules. Skipped for entries materialized by an
-        # external generator: command (those produce the bytes themselves).
-        if in_generator_zone? && @template.nil? && @generator.nil? &&
-           (@format == "markdown" || @format == "text") && !@nested
-          raise UsageError.new("entry '#{@key}': derived #{@format} entries require a template")
-        end
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
-      def parse_compute!(raw)
-        src = raw["compute"]
-        unless src
-          @compute = nil
-          @projection = nil
-          @generator = nil
-          return
-        end
-
-        kind = src["kind"]
-        unless COMPUTE_KINDS.include?(kind)
-          raise BadManifest.new(
-            "entry '#{@key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{kind.inspect})",
-          )
-        end
-
-        @compute = src.freeze
-        if kind == "projection"
-          @projection = @compute
-          @generator  = nil
-        else
-          @generator  = @compute
-          @projection = nil
-        end
-      end
-
-      def parse_intake!(src)
-        src ||= {}
-        @intake_handler = src["handler"]
-        @intake_config  = src["config"] || {}
-      end
-
-      def validate_events!
-        pubsub_events = Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
-        @events.each_key do |evt|
-          next if pubsub_events.include?(evt.to_sym)
-
-          raise UsageError.new(
-            "entry '#{@key}': unknown event '#{evt}' in events: block. " \
-            "Known events: #{pubsub_events.join(", ")}.",
-          )
-        end
-      end
     end
   end
 end

data/lib/textus/manifest.rb

@@ -3,14 +3,6 @@ require_relative "manifest/schema"
 
 module Textus
   class Manifest
-    EXT_TO_FORMAT = {
-      ".md" => "markdown",
-      ".json" => "json",
-      ".yaml" => "yaml",
-      ".yml" => "yaml",
-      ".txt" => "text",
-    }.freeze
-
     TEXTUS_2_HINT = "Install textus 0.11.x to run the migrator, then upgrade to this version. " \
                     "See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110".freeze
 
@@ -81,7 +73,11 @@ module Textus
 
       Schema.validate!(raw)
 
-      @entries = Array(raw["entries"]).map { |e| Manifest::Entry.new(self, e) }
+      @entries = Array(raw["entries"]).map do |e|
+        entry = Manifest::Entry::Parser.call(self, e)
+        Manifest::Entry::Validators.run_all(entry)
+        entry
+      end
       validate_declared_keys!
     end
 
@@ -194,13 +190,7 @@ module Textus
     end
 
     def nested_glob(format)
-      case format
-      when "markdown" then "**/*.md"
-      when "json" then "**/*.json"
-      when "yaml" then "**/*.{yaml,yml}"
-      when "text" then "**/*.txt"
-      else raise UsageError.new("unknown format #{format.inspect} for nested glob")
-      end
+      Textus::Entry.for_format(format).nested_glob
     end
   end
 end

data/lib/textus/operations/reads.rb

@@ -0,0 +1,39 @@
+module Textus
+  class Operations
+    class Reads
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def get
+        Application::Reads::Get.new(ctx: @ctx, orchestrator: orchestrator)
+      end
+
+      def freshness      = Application::Reads::Freshness.new(ctx: @ctx)
+      def audit          = Application::Reads::Audit.new(ctx: @ctx)
+      def blame          = Application::Reads::Blame.new(ctx: @ctx)
+      def policy_explain = Application::Reads::PolicyExplain.new(ctx: @ctx)
+      def list           = Application::Reads::List.new(ctx: @ctx)
+      def where           = Application::Reads::Where.new(ctx: @ctx)
+      def uid             = Application::Reads::Uid.new(ctx: @ctx)
+      def schema_envelope = Application::Reads::SchemaEnvelope.new(ctx: @ctx)
+      def deps            = Application::Reads::Deps.new(ctx: @ctx)
+      def rdeps           = Application::Reads::Rdeps.new(ctx: @ctx)
+      def published       = Application::Reads::Published.new(ctx: @ctx)
+      def stale           = Application::Reads::Stale.new(ctx: @ctx)
+      def validate_all    = Application::Reads::ValidateAll.new(ctx: @ctx)
+
+      private
+
+      def orchestrator
+        Application::Refresh::Orchestrator.new(
+          worker: Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus),
+          bus: @ctx.store.bus,
+          store_root: @ctx.store.root,
+          store: @ctx.store,
+          role: @ctx.role,
+        )
+      end
+    end
+  end
+end

data/lib/textus/operations/refresh.rb

@@ -0,0 +1,27 @@
+module Textus
+  class Operations
+    class Refresh
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def worker
+        Application::Refresh::Worker.new(ctx: @ctx, bus: @ctx.store.bus)
+      end
+
+      def orchestrator
+        Application::Refresh::Orchestrator.new(
+          worker: worker,
+          bus: @ctx.store.bus,
+          store_root: @ctx.store.root,
+          store: @ctx.store,
+          role: @ctx.role,
+        )
+      end
+
+      def all
+        Application::Refresh::All.new(ctx: @ctx, bus: @ctx.store.bus)
+      end
+    end
+  end
+end

data/lib/textus/operations/writes.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Operations
+    class Writes
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def put     = Application::Writes::Put.new(ctx: @ctx, bus: bus)
+      def delete  = Application::Writes::Delete.new(ctx: @ctx, bus: bus)
+      def mv      = Application::Writes::Mv.new(ctx: @ctx, bus: bus)
+      def accept  = Application::Writes::Accept.new(ctx: @ctx, bus: bus)
+      def build   = Application::Writes::Build.new(ctx: @ctx, bus: bus)
+      def publish = Application::Writes::Publish.new(ctx: @ctx, bus: bus)
+      def reject  = Application::Writes::Reject.new(ctx: @ctx, bus: bus)
+
+      private
+
+      def bus = @ctx.store.bus
+    end
+  end
+end

data/lib/textus/operations.rb

@@ -0,0 +1,44 @@
+module Textus
+  # Single canonical entrypoint for invoking application use-cases against a
+  # store. Mirrors the directory structure under `lib/textus/application/`:
+  #
+  #   ops = Textus::Operations.for(store, role: "agent")
+  #   ops.writes.put.call(key, body: "...")
+  #   ops.reads.get.call(key)
+  #   ops.refresh.worker.call(key)
+  #
+  # Replaces the prior `Textus::Composition` module (deleted in v0.12.2).
+  class Operations
+    def self.for(store, role: Role::DEFAULT, correlation_id: nil, dry_run: false)
+      ctx = Application::Context.new(
+        store: store,
+        role: role,
+        correlation_id: correlation_id,
+        dry_run: dry_run,
+      )
+      new(ctx)
+    end
+
+    attr_reader :ctx
+
+    def initialize(ctx)
+      @ctx = ctx
+    end
+
+    def writes
+      @writes ||= Writes.new(@ctx)
+    end
+
+    def reads
+      @reads ||= Reads.new(@ctx)
+    end
+
+    def refresh
+      @refresh ||= Refresh.new(@ctx)
+    end
+
+    def with_role(role)
+      self.class.new(@ctx.with_role(role))
+    end
+  end
+end

data/lib/textus/projection.rb

@@ -17,8 +17,8 @@ module Textus
       keys = collect_keys
       explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
       rows = keys.map do |key|
-        env = @store.get(key)
-        row = pluck(env["_meta"], env["body"])
+        env = Operations.for(@store).reads.get.call(key)
+        row = pluck(env.meta, env.body)
         explicit_pluck ? row : row.merge("_key" => key)
       end
       reduced = apply_reducer(rows)
@@ -40,7 +40,7 @@ module Textus
     def apply_reducer(rows)
       name = @spec["transform"] or return rows
       callable = @store.registry.rpc_callable(:transform_rows, name)
-      view = Application::Context.new(store: @store, role: "human")
+      view = Application::Context.system(@store)
       Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
         callable.call(store: view, rows: rows, config: @spec["transform_config"] || {})
       end
@@ -50,7 +50,8 @@ module Textus
 
     def collect_keys
       prefixes = Array(@spec["select"])
-      prefixes.flat_map { |p| @store.list(prefix: p).map { |row| row["key"] } }.uniq
+      ops = Operations.for(@store)
+      prefixes.flat_map { |p| ops.reads.list.call(prefix: p).map { |row| row["key"] } }.uniq
     end
 
     def pluck(frontmatter, _body)

data/lib/textus/refresh.rb

@@ -1,13 +1,12 @@
 module Textus
   module Refresh
     def self.call(store, key, as:)
-      ctx = Textus::Composition.context(store, role: as)
-      Textus::Composition.refresh_worker(ctx).run(key)
+      Textus::Operations.for(store, role: as).refresh.worker.run(key)
     end
 
     def self.refresh_stale(store, prefix: nil, zone: nil, as: "runner")
-      ctx = Textus::Composition.context(store, role: as)
-      Textus::Application::Refresh::All.call(ctx, prefix: prefix, zone: zone)
+      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

data/lib/textus/schema/tools.rb

@@ -6,8 +6,8 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = store.get(from)
-        meta = env["_meta"]
+        env = Textus::Operations.for(store).reads.get.call(from)
+        meta = env.meta
         schema = {
           "name" => name,
           "required" => meta.keys,
@@ -25,9 +25,9 @@ module Textus
         schema = load_schema(store, name)
         drift = []
         store.manifest.enumerate.each do |row|
-          env = store.get(row[:key])
+          env = Textus::Operations.for(store).reads.get.call(row[:key])
           begin
-            schema.validate!(env["_meta"])
+            schema.validate!(env.meta)
           rescue SchemaViolation => e
             drift << { "key" => row[:key], "details" => e.details }
           end
@@ -49,10 +49,11 @@ module Textus
           end
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
+        ops = Textus::Operations.for(store, role: "human")
         touched = []
         store.manifest.enumerate.each do |row|
-          env = store.get(row[:key])
-          meta = env["_meta"]
+          env = ops.reads.get.call(row[:key])
+          meta = env.meta.dup
           changed = false
           renames.each do |old, new|
             if meta.key?(old)
@@ -62,7 +63,7 @@ module Textus
           end
           next unless changed
 
-          store.put(row[:key], meta: meta, body: env["body"], as: "human")
+          ops.writes.put.call(row[:key], meta: meta, body: env.body)
           touched << row[:key]
         end
         { "protocol" => PROTOCOL, "migrated" => touched, "renames" => renames }

data/lib/textus/store/reader.rb

@@ -46,7 +46,7 @@ module Textus
       # Returns the Textus UID for a key (or nil if the entry has none yet).
       # Raises UnknownKey if the key doesn't resolve to a real file.
       def uid(key)
-        get(key)["uid"]
+        get(key).uid
       end
 
       def deps(key)   = Dependencies.deps_of(@manifest, key)