textus 0.39.1 → 0.41.0

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

@@ -18,7 +18,7 @@ module Textus
           payload =
             if fetch_name
               result = Textus::Write::IntakeFetch.invoke(
-                rpc: store.rpc, handler: fetch_name,
+                caps: store.container, handler: fetch_name,
                 config: { "bytes" => raw }, args: {}, label: "fetch"
               )
               basename = key.split(".").last

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

@@ -0,0 +1,35 @@
+module Textus
+  module Doctor
+    class Check
+      # Flags published files whose recorded source no longer exists in the
+      # store. Per-leaf prune (ADR 0046) reconciles within a still-present
+      # leaf; a renamed or removed *whole* leaf orphans its entire target
+      # directory, which a per-entry build won't revisit. This check catches
+      # that drift without making `build` scan globally.
+      class OrphanedPublishTargets < Check
+        def call
+          sdir = File.join(root, Textus::Ports::SentinelStore::DIR)
+          return [] unless File.directory?(sdir)
+
+          repo_root = File.dirname(root)
+          store = Textus::Ports::SentinelStore.new
+          glob = File.join(sdir, "**", "*#{Textus::Ports::SentinelStore::SUFFIX}")
+          Dir.glob(glob).filter_map do |spath|
+            sentinel = store.load(spath, repo_root)
+            next nil if sentinel.nil? || sentinel.source.nil?
+            next nil if File.exist?(sentinel.source)
+
+            {
+              "code" => "publish.orphaned_target",
+              "level" => "warning",
+              "subject" => sentinel.target,
+              "message" => "published file #{sentinel.target} has no source in the store " \
+                           "(recorded source #{sentinel.source} is gone) — likely a renamed or removed leaf",
+              "fix" => "remove the stale copy and its sentinel: rm '#{sentinel.target}' '#{spath}'",
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0047 Decision 4. A publish_tree entry prunes its WHOLE target dir on
+      # every build. If a derived entry's publish_to writes a file into that same
+      # dir, the tree's prune will delete it unless the tree `ignore`s that
+      # filename. Warn so the author adds the ignore before prune eats the index.
+      class PublishTreeIndexOverlap < Check
+        def call
+          entries = manifest.data.entries
+          trees = entries.select { |e| e.nested? && e.publish_tree }
+          return [] if trees.empty?
+
+          derived_targets = entries.flat_map do |e|
+            Array(e.publish_to).map { |rel| [e, rel] }
+          end
+
+          trees.flat_map do |tree|
+            target_prefix = "#{tree.publish_tree.chomp("/")}/"
+            derived_targets.filter_map do |(derived, rel)|
+              next nil unless rel.start_with?(target_prefix)
+
+              rel_to_target = rel.delete_prefix(target_prefix)
+              next nil if tree.ignored?(rel_to_target)
+
+              issue(tree, derived, rel, rel_to_target)
+            end
+          end
+        end
+
+        private
+
+        def issue(tree, derived, rel, rel_to_target)
+          basename = File.basename(rel_to_target)
+          {
+            "code" => "publish.tree_index_overlap",
+            "level" => "warning",
+            "subject" => tree.key,
+            "message" => "publish_tree '#{tree.publish_tree}' overlaps derived entry " \
+                         "'#{derived.key}' publish_to '#{rel}'; the tree's prune will delete it on rebuild",
+            "fix" => "add a glob covering '#{rel_to_target}' to entry '#{tree.key}' ignore " \
+                     "(e.g. ignore: [\"**/#{basename}\"])",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -24,6 +24,8 @@ module Textus
       Check::RuleAmbiguity,
       Check::HandlerAllowlist,
       Check::FetchLocks,
+      Check::OrphanedPublishTargets,
+      Check::PublishTreeIndexOverlap,
       Check::ProposalTargets,
     ].freeze
 

data/lib/textus/hooks/catalog.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    # The single source of truth for hook event names and their required
+    # kwargs. EventBus, RpcRegistry, and the Loader DSL router all read these
+    # tables directly — the registries do not keep their own copies. Catalog
+    # references no other constant, so it has no load-order cycle, which is
+    # what removed the previous drift hazard (EventBus held a hard-coded
+    # `RPC_EVENTS` list that could fall out of sync with RpcRegistry's table).
+    module Catalog
+      # Pub-sub events: 0..N handlers, fire-and-forget, receive `ctx:`.
+      PUBSUB = {
+        entry_put: %i[ctx key envelope],
+        entry_deleted: %i[ctx key],
+        entry_fetched: %i[ctx key envelope change],
+        entry_renamed: %i[ctx key from_key to_key envelope],
+        build_completed: %i[ctx key envelope sources],
+        proposal_accepted: %i[ctx key target_key],
+        proposal_rejected: %i[ctx key target_key],
+        file_published: %i[ctx key envelope source target],
+        store_loaded: %i[ctx],
+        fetch_started: %i[ctx key mode],
+        fetch_failed: %i[ctx key error_class error_message],
+        fetch_backgrounded: %i[ctx key started_at budget_ms],
+      }.freeze
+
+      # RPC events: single handler, return value matters, receive `caps:`.
+      RPC = {
+        resolve_intake: %i[caps config args],
+        transform_rows: %i[caps rows config],
+        validate: %i[caps],
+      }.freeze
+    end
+  end
+end

data/lib/textus/hooks/event_bus.rb

@@ -7,23 +7,6 @@ module Textus
 
       class HookTimeout < StandardError; end
 
-      EVENTS = {
-        entry_put: %i[ctx key envelope],
-        entry_deleted: %i[ctx key],
-        entry_fetched: %i[ctx key envelope change],
-        entry_renamed: %i[ctx key from_key to_key envelope],
-        build_completed: %i[ctx key envelope sources],
-        proposal_accepted: %i[ctx key target_key],
-        proposal_rejected: %i[ctx key target_key],
-        file_published: %i[ctx key envelope source target],
-        store_loaded: %i[ctx],
-        fetch_started: %i[ctx key mode],
-        fetch_failed: %i[ctx key error_class error_message],
-        fetch_backgrounded: %i[ctx key started_at budget_ms],
-      }.freeze
-
-      RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze
-
       def initialize(error_log: ErrorLog.new)
         @pubsub = Hash.new { |h, k| h[k] = [] }
         @error_handlers = []
@@ -36,9 +19,9 @@ module Textus
 
       def register(event, name, keys: nil, &blk)
         event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
+        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if Catalog::RPC.key?(event_sym)
 
-        required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
+        required = Catalog::PUBSUB[event_sym] or raise UsageError.new("unknown event: #{event}")
         sig = Signature.new(blk)
         missing = sig.missing(required)
         if missing.any?

data/lib/textus/hooks/loader.rb

@@ -12,7 +12,7 @@ module Textus
         # Pubsub registration — delegates to EventBus.
         # Also handles RPC event names by delegating to RpcRegistry.
         def on(event, name, keys: nil, &)
-          if Hooks::RpcRegistry::EVENTS.key?(event.to_sym)
+          if Hooks::Catalog::RPC.key?(event.to_sym)
             @rpc.register(event, name, &)
           else
             @events.register(event, name, keys: keys, &)

data/lib/textus/hooks/rpc_registry.rb

@@ -3,23 +3,15 @@
 module Textus
   module Hooks
     class RpcRegistry
-      EVENTS = {
-        resolve_intake: %i[caps config args],
-        transform_rows: %i[caps rows config],
-        validate: %i[caps],
-      }.freeze
-
-      PUBSUB_EVENTS = EventBus::EVENTS.keys.freeze
-
       def initialize
         @table = Hash.new { |h, k| h[k] = {} }
       end
 
       def register(event, name, &blk)
         event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
+        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if Catalog::PUBSUB.key?(event_sym)
 
-        required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
+        required = Catalog::RPC[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
         sig = Signature.new(blk)
         missing = sig.missing(required)
         raise UsageError.new("#{event_sym} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})") if missing.any?
@@ -38,7 +30,7 @@ module Textus
 
       # Invoke a registered callable, injecting `caps:` only if the callable
       # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
-      # `caps:`-alternative) are rejected at registration time, not here.
+      # `store:`) are rejected at registration time, not here.
       def invoke(event, name, caps:, **other)
         blk = callable(event, name)
         sig = Signature.new(blk)

data/lib/textus/manifest/capabilities.rb

@@ -11,9 +11,9 @@ module Textus
       # declares a `kind: workspace` zone is therefore rejected at load (no
       # `keep`-holder); declare `roles:` to opt into a workspace lane (ADR 0033).
       DEFAULT_MAPPING = {
-        "human" => %w[author propose].freeze,
-        "agent" => %w[propose].freeze,
-        "automation" => %w[fetch build].freeze,
+        Textus::Role::HUMAN => %w[author propose].freeze,
+        Textus::Role::AGENT => %w[propose].freeze,
+        Textus::Role::AUTOMATION => %w[fetch build].freeze,
       }.freeze
 
       # Returns { role_name => [verbs] }. When `roles:` is declared we use

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

@@ -44,6 +44,7 @@ module Textus
         def inject_boot    = false # rubocop:disable Naming/PredicateMethod
         def events         = {}
         def publish_each   = nil
+        def publish_tree   = nil
         def index_filename = nil
         def ignore         = []
 
@@ -78,27 +79,18 @@ module Textus
           end
         end
 
-        # Subclasses override to customize publish behavior.
-        # Default: copy the stored file to each publish_to target.
-        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
-        # Publish#call, or nil to skip.
-        def publish_via(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-          return nil if Array(publish_to).empty?
-
-          source_path = pctx.manifest.resolver.resolve(@key).path
-          envelope = pctx.reader.call(@key)
-
-          publish_to.each do |rel|
-            target_abs = File.join(pctx.repo_root, rel)
-            Textus::Ports::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
-            pctx.emit(:file_published,
-                      key: @key,
-                      envelope: envelope,
-                      source: source_path,
-                      target: target_abs)
-          end
+        # ADR 0049: an entry resolves, once, to one Publish::* mode that owns its
+        # publish algorithm. A plain entry publishes via ToPaths (publish_to) or
+        # None; Nested resolves among the key/path-driven modes. Derived
+        # overrides publish_via to materialize first.
+        def publish_mode
+          @publish_mode ||= Publish.resolve(self)
+        end
 
-          { kind: :built, value: { "key" => @key, "path" => source_path, "published_to" => publish_to } }
+        # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
+        # Write::Publish, or nil to skip.
+        def publish_via(pctx, prefix: nil)
+          publish_mode.publish(pctx, prefix: prefix)
         end
       end
     end

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

@@ -1,16 +1,18 @@
 module Textus
   class Manifest
     class Entry
+      # A directory entry: enumerates a tree of leaves and resolves to one
+      # publish mode (ADR 0049). The publish algorithms themselves live in
+      # Entry::Publish::* — Nested is just the value (attributes + ignore
+      # predicate) those modes read.
       class Nested < Base
-        PUBLISH_EACH_VARS   = Validators::PublishEach::KNOWN_VARS
-        PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
+        attr_reader :index_filename, :publish_each, :publish_tree, :ignore
 
-        attr_reader :index_filename, :publish_each, :ignore
-
-        def initialize(index_filename: nil, publish_each: nil, ignore: nil, **rest)
+        def initialize(index_filename: nil, publish_each: nil, publish_tree: nil, ignore: nil, **rest)
           super(**rest)
           @index_filename = index_filename
           @publish_each = publish_each
+          @publish_tree = publish_tree
           @ignore = Array(ignore)
         end
 
@@ -21,56 +23,13 @@ module Textus
         # an ignored path is excluded, never judged.
         def ignored?(rel_path) = IgnoreMatcher.match?(@ignore, rel_path)
 
-        def publish_target_for(full_key)
-          return nil if @publish_each.nil?
-
-          entry_segs = @key.split(".")
-          key_segs = full_key.split(".")
-          raise UsageError.new("key '#{full_key}' is not under entry '#{@key}'") unless key_segs[0, entry_segs.length] == entry_segs
-
-          remaining = key_segs[entry_segs.length..] || []
-          leaf = remaining.join("/")
-          basename = remaining.last || ""
-          ext = Textus::Entry.for_format(@format).extensions.first.to_s.sub(/^\./, "")
-
-          vars = { "leaf" => leaf, "basename" => basename, "key" => full_key, "ext" => ext }
-          @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
-        end
-
-        def publish_via(pctx, prefix: nil)
-          return nil if @publish_each.nil?
-
-          leaves = []
-          pctx.manifest.resolver.enumerate(prefix: @key).each do |row|
-            next unless row[:manifest_entry].equal?(self)
-            next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-            target_rel = publish_target_for(row[:key])
-            target_abs = File.expand_path(File.join(pctx.repo_root, target_rel))
-            unless target_abs.start_with?(File.expand_path(pctx.repo_root) + File::SEPARATOR)
-              raise Textus::PublishError.new(
-                "entry '#{@key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-              )
-            end
-
-            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
-            pctx.emit(:file_published,
-                      key: row[:key],
-                      envelope: pctx.reader.call(row[:key]),
-                      source: row[:path],
-                      target: target_abs)
-            leaves << { "key" => row[:key], "source" => row[:path], "target" => target_abs }
-          end
-
-          { kind: :leaves, value: leaves }
-        end
-
         KIND = :nested
 
         def self.from_raw(common, raw)
           new(
             index_filename: raw["index_filename"],
             publish_each: raw["publish_each"],
+            publish_tree: raw["publish_tree"],
             ignore: raw["ignore"],
             **common,
           )

data/lib/textus/manifest/entry/publish/each.rb

@@ -0,0 +1,83 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # Shared base for the two key-driven publish_each modes (EachFile,
+        # EachDir). Owns the leaf enumeration, the `{...}` target templating, and
+        # the per-leaf repo-escape guard. Subclasses implement `#publish_leaf`,
+        # returning `{ written:, pruned: }`, and the discriminator half of
+        # `#validate!`.
+        class Each < Mode
+          def publish(pctx, prefix: nil)
+            leaves = []
+            pruned = []
+            pctx.manifest.resolver.enumerate(prefix: entry.key).each do |row|
+              next unless row[:manifest_entry].equal?(entry)
+              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
+
+              target_abs = guarded_target(pctx, row)
+              result = publish_leaf(row, target_abs, pctx)
+              pruned.concat(result[:pruned])
+              result[:written].each do |w|
+                leaves << { "key" => row[:key], "source" => w["source"], "target" => w["target"] }
+              end
+            end
+
+            { kind: :leaves, value: leaves, pruned: pruned }
+          end
+
+          # Expand this entry's publish_each template for a full leaf key.
+          def target_for(full_key)
+            entry_segs = entry.key.split(".")
+            key_segs = full_key.split(".")
+            raise UsageError.new("key '#{full_key}' is not under entry '#{entry.key}'") unless key_segs[0, entry_segs.length] == entry_segs
+
+            remaining = key_segs[entry_segs.length..] || []
+            Template.expand(
+              entry.publish_each,
+              "leaf" => remaining.join("/"),
+              "basename" => remaining.last || "",
+              "key" => full_key,
+              "ext" => ext,
+            )
+          end
+
+          private
+
+          def guarded_target(pctx, row)
+            target_rel = target_for(row[:key])
+            target_abs = repo_abs(pctx, target_rel)
+            return target_abs if inside_repo?(pctx, target_abs)
+
+            raise Textus::PublishError.new(
+              "entry '#{entry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
+            )
+          end
+
+          def ext
+            Textus::Entry.for_format(entry.format).extensions.first.to_s.sub(/^\./, "")
+          end
+
+          # publish_each shape rules common to file and directory leaves: a
+          # String value with only known template vars. Returns the used vars so
+          # subclasses can apply their discriminator rule.
+          def validate_template_basics
+            publish_each = entry.publish_each
+            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless publish_each.is_a?(String)
+
+            used_vars = publish_each.scan(Template::VAR_RE).flatten
+            unknown = used_vars - Template::KNOWN_VARS
+            unless unknown.empty?
+              raise UsageError.new(
+                "entry '#{entry.key}': publish_each uses unknown template variable(s) " \
+                "#{unknown.map { |v| "{#{v}}" }.join(", ")}. Known: #{Template::KNOWN_VARS.map { |v| "{#{v}}" }.join(", ")}.",
+              )
+            end
+
+            used_vars
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/publish/each_dir.rb

@@ -0,0 +1,74 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # publish_each + index_filename (ADR 0046): each leaf is a whole subtree
+        # copied into one templated directory, layout preserved, then pruned.
+        # The template names the target DIRECTORY (not the index file).
+        class EachDir < Each
+          def publish_leaf(row, target_abs, pctx)
+            SubtreeMirror.new(entry, pctx).mirror(
+              base: store_base(pctx),
+              walk_root: File.dirname(row[:path]),
+              target_dir: target_abs,
+              key: row[:key],
+              envelope: pctx.reader.call(row[:key]),
+              prune_honors_ignore: false,
+            )
+          end
+
+          def validate!
+            used_vars = validate_template_basics
+            reject_file_only_vars(used_vars)
+            reject_index_filename_segment
+            reject_file_looking_segment
+            return if used_vars.intersect?(%w[leaf key])
+
+            raise UsageError.new(
+              "entry '#{entry.key}': directory-leaf publish_each must reference {leaf} or {key} " \
+              "(else every leaf would clobber the same directory).",
+            )
+          end
+
+          private
+
+          def reject_file_only_vars(used_vars)
+            forbidden = used_vars & %w[basename ext]
+            return if forbidden.empty?
+
+            raise UsageError.new(
+              "entry '#{entry.key}': publish_each names a directory " \
+              "(index_filename: '#{entry.index_filename}'); {basename}/{ext} are file-only — " \
+              "use {leaf} or {key}.",
+            )
+          end
+
+          def reject_index_filename_segment
+            return unless last_segment == entry.index_filename
+
+            raise UsageError.new(
+              "entry '#{entry.key}': directory-leaf publish_each must name the target DIRECTORY, " \
+              "not the index file — drop the trailing '/#{entry.index_filename}' " \
+              "(the whole leaf subtree is copied into the named directory).",
+            )
+          end
+
+          def reject_file_looking_segment
+            ext = File.extname(last_segment)
+            return if ext.empty?
+
+            raise UsageError.new(
+              "entry '#{entry.key}': directory-leaf publish_each names a DIRECTORY target, but its " \
+              "final segment '#{last_segment}' looks like a file (extension '#{ext}') — " \
+              "drop the extension (the whole leaf subtree is copied into the named directory).",
+            )
+          end
+
+          def last_segment
+            entry.publish_each.sub(%r{/\z}, "").split("/").last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/publish/each_file.rb

@@ -0,0 +1,29 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # publish_each over file leaves (no index_filename): one stored leaf file
+        # copied to one templated repo path. No prune — each leaf is a single
+        # file, not a subtree.
+        class EachFile < Each
+          def publish_leaf(row, target_abs, pctx)
+            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
+                                       source: row[:path], target: target_abs)
+            { written: [{ "source" => row[:path], "target" => target_abs }], pruned: [] }
+          end
+
+          def validate!
+            used_vars = validate_template_basics
+            return if used_vars.intersect?(Template::REQUIRED_DISCRIMINATOR_VARS)
+
+            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/publish/mode.rb

@@ -0,0 +1,39 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # Base for every publish mode: wraps the resolved entry and owns the one
+        # repo-root escape guard the writing modes share (ADR 0049). Subclasses
+        # implement `#publish(pctx, prefix:)` returning the existing
+        # `{ kind:, value:, pruned: }` shape (or nil), and `#validate!` for the
+        # per-mode shape rules reached *because* this mode resolved.
+        class Mode
+          def initialize(entry)
+            @entry = entry
+          end
+
+          attr_reader :entry
+
+          # No shape rules by default — ToPaths/None publish without templating.
+          def validate!; end
+
+          private
+
+          # Expand `rel` under repo_root and confirm it stays inside it.
+          def repo_abs(pctx, rel)
+            File.expand_path(File.join(pctx.repo_root, rel))
+          end
+
+          def inside_repo?(pctx, abs)
+            abs.start_with?(File.expand_path(pctx.repo_root) + File::SEPARATOR)
+          end
+
+          # Store-side directory this entry's tree lives under.
+          def store_base(pctx)
+            File.join(pctx.root, "zones", entry.path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/publish/none.rb

@@ -0,0 +1,14 @@
+module Textus
+  class Manifest
+    class Entry
+      module Publish
+        # An entry with no publish_* key — nothing to publish.
+        class None < Mode
+          def publish(_pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
+            nil
+          end
+        end
+      end
+    end
+  end
+end