textus 0.18.0 → 0.20.0

data/lib/textus/application/tools/migrate_keys.rb

@@ -0,0 +1,191 @@
+module Textus
+  module Application
+    module Tools
+      # Run-once helper that renames files/directories whose basenames don't
+      # conform to the strict key grammar (§3 of plan-1.2). Only walks
+      # nested: true manifest entries — leaf entries with illegal declared
+      # keys are caught by Manifest load and must be fixed by hand.
+      module MigrateKeys
+        SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
+
+        module_function
+
+        # Returns the envelope hash described in plan-1.2 §3.
+        def run(store, write: false)
+          plan = build_plan(store)
+          collisions = plan[:collisions]
+          renames = plan[:renames]
+
+          ok = collisions.empty?
+          apply!(store, renames) if write && ok
+
+          {
+            "protocol" => Textus::PROTOCOL,
+            "mode" => write ? "write" : "dry-run",
+            "renames" => renames.map { |r| envelope_rename(r) },
+            "collisions" => collisions.map { |c| envelope_collision(c) },
+            "ok" => ok,
+          }
+        end
+
+        # ------------------------------------------------------------------
+        # Plan construction
+        # ------------------------------------------------------------------
+
+        # Returns { renames: [...], collisions: [...] }
+        # Each rename: { from:, to:, old_key:, new_key:, kind: :file|:dir }
+        # Each collision: { target:, sources: [...] }
+        def build_plan(store) # rubocop:disable Metrics/AbcSize
+          renames = []
+          target_buckets = Hash.new { |h, k| h[k] = [] } # target_path => [source_path, ...]
+
+          store.manifest.entries.each do |entry|
+            next unless entry.nested?
+
+            base = File.join(store.root, "zones", entry.path)
+            next unless File.directory?(base)
+
+            # Walk depth-first. Order matters when computing the "new key"
+            # for files inside a renamed directory: we record renames bottom-up,
+            # so children are renamed before their parents on apply.
+            walk(base) do |abs_path, is_dir|
+              next if abs_path == base
+
+              basename = File.basename(abs_path)
+              stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
+              next if stem.match?(SEGMENT)
+
+              new_stem = normalize(stem)
+              # Skip if normalization yields the same stem (e.g. already-legal
+              # under a different lens). In practice match?(SEGMENT) catches that
+              # above; this is a safety net.
+              next if new_stem == stem
+
+              new_basename = is_dir ? new_stem : new_stem + File.extname(basename)
+              target = File.join(File.dirname(abs_path), new_basename)
+              target_buckets[target] << abs_path
+
+              renames << {
+                from: abs_path,
+                to: target,
+                kind: is_dir ? :dir : :file,
+                entry: entry,
+                base: base,
+              }
+            end
+          end
+
+          collisions = target_buckets.select { |_, srcs| srcs.length > 1 }
+                                     .map { |t, srcs| { target: t, sources: srcs.sort } }
+
+          # Drop colliding entries from renames (we won't apply any of them)
+          colliding_targets = collisions.to_set { |c| c[:target] }
+          renames.reject! { |r| colliding_targets.include?(r[:to]) }
+
+          # Sort renames bottom-up (deepest path first) so children move before parents.
+          renames.sort_by! { |r| -r[:from].count("/") }
+
+          { renames: renames, collisions: collisions }
+        end
+
+        # Yields [absolute_path, is_dir] for every entry under root. Depth-first.
+        def walk(root, &block)
+          Dir.each_child(root) do |name|
+            abs = File.join(root, name)
+            if File.directory?(abs)
+              walk(abs, &block)
+              yield abs, true
+            else
+              yield abs, false
+            end
+          end
+        end
+
+        # Deterministic transform per plan §3.
+        def normalize(s)
+          s = s.downcase
+          s = s.gsub(/[^a-z0-9-]/, "-") # ., _, and anything else become -
+          s = s.gsub(/-+/, "-")
+          s.sub(/\A-+/, "").sub(/-+\z/, "")
+        end
+
+        # ------------------------------------------------------------------
+        # Apply
+        # ------------------------------------------------------------------
+
+        def apply!(store, renames)
+          audit = Textus::Infra::AuditLog.new(store.root)
+          renames.each do |r|
+            # Bottom-up order means a child's ancestors haven't moved yet, so
+            # `from`/`to` are valid as-recorded. The audit `key` reflects the
+            # eventual full key once every rename in this batch has applied.
+            from = r[:from]
+            to = r[:to]
+            File.rename(from, to)
+            new_key = compute_new_key(r, renames)
+            audit.append(
+              role: "runner",
+              verb: "migrate-keys",
+              key: new_key,
+              etag_before: nil,
+              etag_after: nil,
+              extras: { "from" => from, "to" => to },
+            )
+          end
+        end
+
+        # If an ancestor of `path` was renamed earlier in this batch, rewrite the path.
+        def resolve_current_path(path, renames)
+          out = path
+          renames.each do |r|
+            prefix = r[:from] + "/"
+            out = r[:to] + out[r[:from].length..] if out.start_with?(prefix)
+          end
+          out
+        end
+
+        # New full key after applying all renames up through this one.
+        def compute_new_key(rename, renames)
+          base = rename[:base]
+          entry = rename[:entry]
+          new_to = resolve_current_path(rename[:to], renames)
+
+          rel = new_to.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+          stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "") unless rename[:kind] == :dir
+          stripped ||= rel
+          segs = stripped.split("/").reject(&:empty?)
+          (entry.key.split(".") + segs).join(".")
+        end
+
+        # ------------------------------------------------------------------
+        # Envelope helpers
+        # ------------------------------------------------------------------
+
+        def envelope_rename(r)
+          {
+            "from" => r[:from],
+            "to" => r[:to],
+            "old_key" => path_to_key(r[:from], r[:base], r[:entry], r[:kind]),
+            "new_key" => path_to_key(r[:to], r[:base], r[:entry], r[:kind]),
+          }
+        end
+
+        def envelope_collision(col)
+          { "target" => col[:target], "sources" => col[:sources] }
+        end
+
+        def path_to_key(path, base, entry, kind)
+          rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+          stripped =
+            if kind == :dir
+              rel
+            else
+              rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+            end
+          segs = stripped.split("/").reject(&:empty?)
+          (entry.key.split(".") + segs).join(".")
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/tools/migrate_manifest_to_kinds.rb

@@ -0,0 +1,31 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Tools
+      module MigrateManifestToKinds
+        module_function
+
+        def upgrade_yaml(yaml_text)
+          raw = YAML.safe_load(yaml_text, aliases: false)
+          raw["entries"] = Array(raw["entries"]).map { |row| upgrade_row(row) }
+          YAML.dump(raw)
+        end
+
+        def upgrade_row(row)
+          return row if row["kind"]
+
+          row.merge("kind" => infer_kind(row))
+        end
+
+        def infer_kind(row)
+          return "intake"  if row["intake"].is_a?(Hash) || row["intake_handler"]
+          return "derived" if row["template"] || row["compute"] || row["generator"] || row["projection"]
+          return "nested"  if row["nested"] == true
+
+          "leaf"
+        end
+      end
+    end
+  end
+end

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

@@ -2,15 +2,23 @@ module Textus
   module Application
     module Writes
       class Accept
-        def initialize(ctx:, envelope_io:)
-          @ctx = ctx
-          @envelope_io = envelope_io
+        def initialize(ctx:, manifest:, file_store:, schemas:, envelope_io:, bus:, authorizer:, hook_context:) # rubocop:disable Metrics/ParameterLists
+          @ctx          = ctx
+          @manifest     = manifest
+          @file_store   = file_store
+          @schemas      = schemas
+          @envelope_io  = envelope_io
+          @bus          = bus
+          @authorizer   = authorizer
+          @hook_context = hook_context
         end
 
         def call(pending_key)
           raise ProposalError.new("only human role can accept proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
 
-          env = Textus::Application::Reads::Get.new(ctx: @ctx).call(pending_key)
+          env = Textus::Application::Reads::Get.new(
+            ctx: @ctx, manifest: @manifest, file_store: @file_store,
+          ).call(pending_key)
           proposal = env.meta["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
           target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
           action = proposal["action"] || "put"
@@ -23,33 +31,48 @@ module Textus
             # target. Not related to the removed intake-handler legacy bridge.
             target_meta = env.meta["frontmatter"] || {}
             target_body = env.body
-            Textus::Application::Writes::Put.new(ctx: @ctx, envelope_io: @envelope_io).call(target, meta: target_meta, body: target_body)
+            put_op.call(target, meta: target_meta, body: target_body)
           when "delete"
-            Textus::Application::Writes::Delete.new(ctx: @ctx, envelope_io: @envelope_io).call(target)
+            delete_op.call(target)
           else
             raise ProposalError.new("unknown action: #{action}")
           end
 
-          Textus::Application::Writes::Delete.new(ctx: @ctx, envelope_io: @envelope_io).call(pending_key)
+          delete_op.call(pending_key)
 
-          @ctx.bus.publish(:proposal_accepted,
-                           store: @ctx.with_role(@ctx.role),
-                           key: pending_key,
-                           target_key: target,
-                           correlation_id: @ctx.correlation_id)
+          @bus.publish(:proposal_accepted,
+                       ctx: @hook_context,
+                       key: pending_key,
+                       target_key: target)
 
           { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
         end
 
         private
 
+        def put_op
+          @put_op ||= Textus::Application::Writes::Put.new(
+            ctx: @ctx, manifest: @manifest, envelope_io: @envelope_io,
+            bus: @bus, authorizer: @authorizer, hook_context: @hook_context
+          )
+        end
+
+        def delete_op
+          @delete_op ||= Textus::Application::Writes::Delete.new(
+            ctx: @ctx, manifest: @manifest, envelope_io: @envelope_io,
+            bus: @bus, authorizer: @authorizer, hook_context: @hook_context
+          )
+        end
+
         def evaluate_promotion!(env, target_key)
-          rules = @ctx.manifest.rules_for(target_key)
+          rules = @manifest.rules_for(target_key)
           promote = rules.promote
           return if promote.nil? || promote.requires.empty?
 
-          policy = Textus::Domain::Policy::Promotion.from_names(promote.requires)
-          result = policy.evaluate(entry: env, store: @ctx.store)
+          policy = Textus::Application::Policy::Promotion.from_names(promote.requires)
+          result = policy.evaluate(
+            entry: env, schemas: @schemas, manifest: @manifest, role: @ctx.role,
+          )
           return if result.ok?
 
           raise ProposalError.new(

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

@@ -2,24 +2,27 @@ module Textus
   module Application
     module Writes
       class Delete
-        def initialize(ctx:, envelope_io:)
-          @ctx = ctx
-          @envelope_io = envelope_io
+        def initialize(ctx:, manifest:, envelope_io:, bus:, authorizer:, hook_context:)
+          @ctx          = ctx
+          @manifest     = manifest
+          @envelope_io  = envelope_io
+          @bus          = bus
+          @authorizer   = authorizer
+          @hook_context = hook_context
         end
 
         def call(key, if_etag: nil, suppress_events: false)
-          @ctx.manifest.validate_key!(key)
-          mentry = @ctx.manifest.resolve(key).entry
+          @manifest.validate_key!(key)
+          mentry = @manifest.resolver.resolve(key).entry
 
-          @ctx.authorize_write!(mentry)
+          @authorizer.authorize_write!(mentry, role: @ctx.role)
 
           @envelope_io.delete(key, mentry: mentry, if_etag: if_etag)
 
           unless suppress_events
-            @ctx.bus.publish(:entry_deleted,
-                             store: @ctx.with_role(@ctx.role),
-                             key: key,
-                             correlation_id: @ctx.correlation_id)
+            @bus.publish(:entry_deleted,
+                         ctx: @hook_context,
+                         key: key)
           end
 
           { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }

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

@@ -1,3 +1,5 @@
+require "fileutils"
+
 module Textus
   module Application
     module Writes
@@ -6,7 +8,7 @@ module Textus
       # AuditLog, Manifest) instead of File/FileUtils and Store directly.
       #
       # No permission check, no event firing — those belong to the caller
-      # (Application::Writes::Put / ::Delete).
+      # (Application::Writes::Put / ::Delete / ::Mv).
       class EnvelopeIO
         Payload = Data.define(:meta, :body, :content)
 
@@ -18,8 +20,28 @@ module Textus
           @ctx        = ctx
         end
 
+        def exists?(path) = @file_store.exists?(path)
+
+        # Reads an envelope by key, returning nil when absent. Used by Mv
+        # to inspect pre-move state (UID presence, content surfacing) so
+        # the move pipeline can consolidate I/O in one place.
+        def read_envelope(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)
+          Envelope.build(
+            key: key, mentry: mentry, path: path,
+            meta: parsed["_meta"], body: parsed["body"],
+            etag: Etag.for_bytes(raw), content: parsed["content"]
+          )
+        end
+
         def write(key, mentry:, payload:, if_etag: nil)
-          path = @manifest.resolve(key).path
+          path = @manifest.resolver.resolve(key).path
 
           meta = payload.meta || {}
           strategy = Entry.for_format(mentry.format)
@@ -60,8 +82,8 @@ module Textus
 
         def delete(key, mentry:, if_etag: nil)
           _ = mentry
-          path = @manifest.resolve(key).path
-          raise UnknownKey.new(key, suggestions: @manifest.suggestions_for(key)) unless @file_store.exists?(path)
+          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
@@ -74,6 +96,44 @@ module Textus
           )
         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)
+          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 = 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"] = @ctx.correlation_id if @ctx.correlation_id
+
+          @audit_log.append(
+            role: @ctx.role, verb: "mv", key: to_key,
+            etag_before: etag_before, etag_after: etag_after,
+            extras: extras
+          )
+
+          envelope
+        end
+
         private
 
         def existing_uid_for(mentry, path)

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

@@ -0,0 +1,50 @@
+require "fileutils"
+
+module Textus
+  module Application
+    module Writes
+      # Materializes a single Derived manifest entry onto disk by running
+      # the builder pipeline (template + projection + external runner).
+      # Extracted from Application::Writes::Build so that Publish can reuse
+      # it without creating a Build dependency.
+      class Materializer
+        def initialize(ctx:, manifest:, file_store:, bus:, root:, store:)
+          @ctx        = ctx
+          @manifest   = manifest
+          @file_store = file_store
+          @bus        = bus
+          @root       = root
+          @store      = store
+        end
+
+        # Runs the builder pipeline for `mentry` and returns the on-disk
+        # target_path string.
+        def run(mentry)
+          reader = Textus::Application::Reads::Get.new(
+            ctx: @ctx, manifest: @manifest, file_store: @file_store,
+          )
+          lister = Textus::Application::Reads::List.new(manifest: @manifest)
+          Builder::Pipeline.run(
+            mentry: mentry,
+            manifest: @manifest,
+            reader: reader.method(:call),
+            lister: lister.method(:call),
+            transform_resolver: ->(name) { @bus.rpc_callable(:transform_rows, name) },
+            template_loader: ->(name) { read_template(name) },
+            transform_context: @store,
+            inject_intro: -> { Textus::Intro.run(@store) },
+          )
+        end
+
+        private
+
+        def read_template(name)
+          tpl_path = File.join(@root, "templates", name)
+          raise TemplateError.new("template not found: #{tpl_path}", template_name: name) unless File.exist?(tpl_path)
+
+          File.read(tpl_path)
+        end
+      end
+    end
+  end
+end