textus 0.4.0 → 0.8.0

data/lib/textus/builder/pipeline.rb

@@ -0,0 +1,56 @@
+require "fileutils"
+require "time"
+
+module Textus
+  class Builder
+    module InjectMeta
+      # Returns a new hash with _meta as the first key, per SPEC §6 ordering.
+      def self.call(content_hash, mentry)
+        meta = { "generated_at" => Time.now.utc.iso8601 }
+        from = Array(mentry.projection&.fetch("select", nil)).compact
+        meta["from"] = from unless from.empty?
+        meta["template"] = mentry.template if mentry.template
+        reduce = mentry.projection&.dig("reduce")
+        meta["reduce"] = reduce if reduce
+
+        out = { "_meta" => meta }
+        content_hash.each { |k, v| out[k] = v unless k == "_meta" }
+        out
+      end
+    end
+
+    module Pipeline
+      def self.renderers
+        @renderers ||= {
+          "markdown" => Renderer::Markdown,
+          "text" => Renderer::Text,
+          "json" => Renderer::Json,
+          "yaml" => Renderer::Yaml,
+        }
+      end
+
+      def self.run(store:, mentry:, template_loader:)
+        # 1. Load sources + project + reduce
+        data =
+          if mentry.projection
+            Projection.new(store, mentry.projection).run
+          else
+            { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
+          end
+        data = data.merge("intro" => Intro.run(store)) if mentry.inject_intro
+
+        # 2. Render
+        klass = renderers[mentry.format] or
+          raise UsageError.new("builder: unsupported format #{mentry.format.inspect} for '#{mentry.key}'")
+        bytes = klass.new(template_loader: template_loader).call(mentry: mentry, data: data)
+
+        # 3. Write
+        target_path = Key::Path.resolve(store.manifest, mentry)
+        FileUtils.mkdir_p(File.dirname(target_path))
+        File.binwrite(target_path, bytes)
+
+        target_path
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+require "json"
+
+module Textus
+  class Builder
+    class Renderer
+      class Json < Renderer
+        def call(mentry:, data:)
+          content = mentry.template ? parse_rendered_template!(mentry, data) : default_shape(mentry, data)
+          final = InjectMeta.call(content, mentry)
+          Entry.for_format("json").serialize(meta: {}, body: "", content: final)
+        end
+
+        private
+
+        def parse_rendered_template!(mentry, data)
+          rendered = Mustache.render(@template_loader.call(mentry.template), data)
+          begin
+            parsed = ::JSON.parse(rendered)
+          rescue ::JSON::ParserError => e
+            raise BadRender.new("entry '#{mentry.key}': template did not render valid json: #{e.message}", format: "json")
+          end
+          unless parsed.is_a?(Hash)
+            raise BadRender.new("entry '#{mentry.key}': template must render a top-level object/mapping",
+                                format: "json")
+          end
+
+          parsed
+        end
+
+        def default_shape(mentry, data)
+          if mentry.projection && mentry.projection["reduce"] && data.is_a?(Hash) && !data.key?("entries")
+            data
+          elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
+            { "entries" => data["entries"] }
+          else
+            data.is_a?(Hash) ? data : { "entries" => Array(data) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+require "time"
+
+module Textus
+  class Builder
+    class Renderer
+      class Markdown < Renderer
+        def call(mentry:, data:)
+          raise TemplateError.new("entry '#{mentry.key}': markdown build requires a template") unless mentry.template
+
+          body = Mustache.render(@template_loader.call(mentry.template), data)
+          frontmatter = {
+            "generated" => {
+              "at" => Time.now.utc.iso8601,
+              "from" => Array(mentry.projection&.fetch("select", nil)).compact,
+            },
+          }
+          Entry.for_format("markdown").serialize(meta: frontmatter, body: body)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Textus
+  class Builder
+    class Renderer
+      class Text < Renderer
+        def call(mentry:, data:)
+          raise TemplateError.new("entry '#{mentry.key}': text build requires a template") unless mentry.template
+
+          body = Mustache.render(@template_loader.call(mentry.template), data)
+          Entry.for_format("text").serialize(meta: {}, body: body)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+require "yaml"
+
+module Textus
+  class Builder
+    class Renderer
+      class Yaml < Renderer
+        def call(mentry:, data:)
+          content = mentry.template ? parse_rendered_template!(mentry, data) : default_shape(mentry, data)
+          final = InjectMeta.call(content, mentry)
+          Entry.for_format("yaml").serialize(meta: {}, body: "", content: final)
+        end
+
+        private
+
+        def parse_rendered_template!(mentry, data)
+          rendered = Mustache.render(@template_loader.call(mentry.template), data)
+          begin
+            parsed = ::YAML.safe_load(rendered, permitted_classes: [Date, Time], aliases: false)
+          rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::AliasesNotEnabled => e
+            raise BadRender.new("entry '#{mentry.key}': template did not render valid yaml: #{e.message}", format: "yaml")
+          end
+          unless parsed.is_a?(Hash)
+            raise BadRender.new("entry '#{mentry.key}': template must render a top-level object/mapping",
+                                format: "yaml")
+          end
+
+          parsed
+        end
+
+        def default_shape(mentry, data)
+          if mentry.projection && mentry.projection["reduce"] && data.is_a?(Hash) && !data.key?("entries")
+            data
+          elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
+            { "entries" => data["entries"] }
+          else
+            data.is_a?(Hash) ? data : { "entries" => Array(data) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/builder/renderer.rb

@@ -0,0 +1,17 @@
+module Textus
+  class Builder
+    # Abstract base for output renderers. Each concrete renderer owns
+    # producing the bytes for one manifest format (markdown/json/yaml/text).
+    class Renderer
+      def initialize(template_loader:)
+        @template_loader = template_loader
+      end
+
+      def call(mentry:, data:)
+        _ = mentry
+        _ = data
+        raise NotImplementedError.new("#{self.class.name}#call not implemented")
+      end
+    end
+  end
+end

data/lib/textus/builder.rb

@@ -1,7 +1,4 @@
 require "fileutils"
-require "json"
-require "time"
-require "yaml"
 
 module Textus
   class Builder
@@ -59,122 +56,20 @@ module Textus
     end
 
     def materialize(mentry)
-      data =
-        if mentry.projection
-          Projection.new(@store, mentry.projection).run
-        else
-          { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
-        end
-
-      bytes =
-        case mentry.format
-        when "markdown" then build_markdown(mentry, data)
-        when "text"     then build_text(mentry, data)
-        when "json"     then build_structured(mentry, data, "json")
-        when "yaml"     then build_structured(mentry, data, "yaml")
-        else raise UsageError.new("builder: unsupported format #{mentry.format.inspect} for '#{mentry.key}'")
-        end
-
-      target_path = File.join(@root, "zones", mentry.path)
-      FileUtils.mkdir_p(File.dirname(target_path))
-      File.binwrite(target_path, bytes)
-
+      target_path = Pipeline.run(
+        store: @store,
+        mentry: mentry,
+        template_loader: ->(name) { read_template(name) },
+      )
       publish_and_fire(mentry, target_path)
       { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
     end
 
-    # Markdown: projection -> template -> markdown.serialize(frontmatter, body).
-    # Frontmatter carries the legacy `generated:` bookkeeping block. Per plan-1.2 §6,
-    # `_meta` ordering applies to structured formats only; markdown keeps existing shape
-    # for backward compat with consumers reading frontmatter["generated"]["at"].
-    def build_markdown(mentry, data)
-      data = data.merge("intro" => Intro.run(@store)) if mentry.inject_intro
-      body = render_template!(mentry, data)
-      frontmatter = {
-        "generated" => {
-          "at" => Time.now.utc.iso8601,
-          "from" => Array(mentry.projection&.fetch("select", nil)).compact,
-        },
-      }
-      Entry.for_format("markdown").serialize(frontmatter: frontmatter, body: body)
-    end
-
-    # Text: projection -> template -> text.serialize(body). No frontmatter, no _meta.
-    def build_text(mentry, data)
-      data = data.merge("intro" => Intro.run(@store)) if mentry.inject_intro
-      body = render_template!(mentry, data)
-      Entry.for_format("text").serialize(frontmatter: {}, body: body)
-    end
-
-    # JSON / YAML pipeline. Templateless = default; template = escape hatch.
-    def build_structured(mentry, data, format)
-      strategy = Entry.for_format(format)
-
-      content =
-        if mentry.template
-          parse_rendered_template!(mentry, data, format)
-        else
-          # Default rule: if the reducer returned a Hash (it replaced `rows`), use it as-is.
-          # Otherwise wrap the entries list as { "entries" => [...] } so the top level is a Hash
-          # (required to carry _meta).
-          if mentry.projection && mentry.projection["reducer"] && data.is_a?(Hash) && !data.key?("entries")
-            data
-          elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
-            { "entries" => data["entries"] }
-          else
-            data.is_a?(Hash) ? data : { "entries" => Array(data) }
-          end
-        end
-
-      final = inject_meta(content, mentry)
-      strategy.serialize(frontmatter: {}, body: "", content: final)
-    end
+    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)
 
-    def render_template!(mentry, data)
-      raise TemplateError.new("entry '#{mentry.key}': #{mentry.format} build requires a template") unless mentry.template
-
-      tpl_path = File.join(@root, "templates", mentry.template)
-      raise TemplateError.new("template not found: #{tpl_path}", template_name: mentry.template) unless File.exist?(tpl_path)
-
-      Mustache.render(File.read(tpl_path), data)
-    end
-
-    def parse_rendered_template!(mentry, data, format)
-      tpl_path = File.join(@root, "templates", mentry.template)
-      raise TemplateError.new("template not found: #{tpl_path}", template_name: mentry.template) unless File.exist?(tpl_path)
-
-      rendered = Mustache.render(File.read(tpl_path), data)
-      begin
-        parsed =
-          case format
-          when "json" then ::JSON.parse(rendered)
-          when "yaml" then ::YAML.safe_load(rendered, permitted_classes: [Date, Time], aliases: false)
-          end
-      rescue ::JSON::ParserError, Psych::SyntaxError, Psych::DisallowedClass, Psych::AliasesNotEnabled => e
-        raise BadRender.new("entry '#{mentry.key}': template did not render valid #{format}: #{e.message}", format: format)
-      end
-      unless parsed.is_a?(Hash)
-        raise BadRender.new("entry '#{mentry.key}': template must render a top-level object/mapping",
-                            format: format)
-      end
-
-      parsed
-    end
-
-    # Builds the _meta block per §6 ordering and inserts it as the first top-level key.
-    def inject_meta(content_hash, mentry)
-      meta = {}
-      meta["generated_at"] = Time.now.utc.iso8601
-      from = Array(mentry.projection&.fetch("select", nil)).compact
-      meta["from"] = from unless from.empty?
-      meta["template"] = mentry.template if mentry.template
-      reducer = mentry.projection&.dig("reducer")
-      meta["reducer"] = reducer if reducer
-
-      # Rebuild so _meta appears first; user content follows.
-      out = { "_meta" => meta }
-      content_hash.each { |k, v| out[k] = v unless k == "_meta" }
-      out
+      File.read(tpl_path)
     end
 
     def publish_and_fire(mentry, target_path)

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

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Group
+      class Hook < Group
+        self.cli_name = "hook"
+        subcommands["list"] = Verb::Hooks
+        subcommands["run"]  = Verb::HookRun
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Group
+      class Key < Group
+        self.cli_name = "key"
+        subcommands["mv"]      = Verb::Mv
+        subcommands["uid"]     = Verb::Uid
+        subcommands["migrate"] = Verb::MigrateKeys
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Textus
+  class CLI
+    class Group
+      class Schema < Group
+        self.cli_name = "schema"
+        subcommands["show"]    = Verb::Schema
+        subcommands["init"]    = Verb::SchemaInit
+        subcommands["diff"]    = Verb::SchemaDiff
+        subcommands["migrate"] = Verb::SchemaMigrate
+      end
+    end
+  end
+end

data/lib/textus/cli/group.rb

@@ -0,0 +1,51 @@
+module Textus
+  class CLI
+    class Group < Verb
+      class << self
+        def subcommands
+          @subcommands ||= {}
+        end
+
+        def cli_name
+          @cli_name || raise("subclass must define cli_name")
+        end
+
+        attr_writer :cli_name
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@subcommands, {})
+        end
+
+        def needs_store?
+          # Delegate to the matched subcommand at parse time; default true.
+          true
+        end
+      end
+
+      def parse(argv)
+        subname = argv.shift
+        if subname.nil?
+          raise UsageError.new(
+            "#{self.class.cli_name} requires a subcommand: #{self.class.subcommands.keys.join(", ")}",
+          )
+        end
+
+        @sub_klass = self.class.subcommands[subname]
+        unless @sub_klass
+          raise UsageError.new(
+            "unknown #{self.class.cli_name} subcommand '#{subname}'. " \
+            "Valid: #{self.class.subcommands.keys.join(", ")}",
+          )
+        end
+
+        @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
+        @sub.parse(argv)
+      end
+
+      def call(store)
+        @sub.call(@sub_klass.needs_store? ? store : nil)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class Verb
+      class Accept < Verb
+        option :as_flag, "--as=ROLE"
+
+        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))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Textus
+  class CLI
+    class Verb
+      class Build < Verb
+        option :prefix, "--prefix=K"
+
+        def call(store)
+          emit(Textus::Builder.new(store).build(prefix: prefix))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Textus
+  class CLI
+    class Verb
+      class Delete < Verb
+        option :as_flag, "--as=ROLE"
+        option :if_etag, "--if-etag=E"
+
+        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))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Verb
+      class Deps < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("deps requires a key")
+          emit({ "key" => key, "deps" => store.deps(key) })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class Verb
+      class Doctor < Verb
+        option :checks, "--check=NAME"
+
+        def call(store)
+          check_list = checks&.split(",")&.map(&:strip)
+          res = Textus::Doctor.run(store, checks: check_list)
+          emit(res, exit_code: res["ok"] ? 0 : 1)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Verb
+      class Get < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("get requires a key")
+          emit(store.get(key))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Textus
+  class CLI
+    class Verb
+      class HookRun < Verb
+        def parse(argv)
+          @raw_argv = argv
+        end
+
+        def call(store)
+          name = @raw_argv.shift
+          raise UsageError.new("hook run requires a name") if name.nil?
+
+          as_flag = nil
+          args = {}
+          @raw_argv.each do |tok|
+            case tok
+            when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
+            when /\A--format=/           then next
+            when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
+            else
+              raise UsageError.new("unknown arg to 'hook run #{name}': #{tok}")
+            end
+          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)
+
+          begin
+            Timeout.timeout(Textus::Refresh::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",
+            )
+          rescue Textus::Error
+            raise
+          rescue StandardError => e
+            raise UsageError.new("hook run '#{name}' raised: #{e.class}: #{e.message}")
+          end
+
+          emit({ "action" => name, "ok" => true })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Textus
+  class CLI
+    class Verb
+      class Hooks < Verb
+        option :event_filter, "--event=E"
+
+        def call(store) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+          subcommand = positional.first
+          if subcommand
+            raise UsageError.new("hook requires 'list'") unless subcommand == "list"
+
+            positional.shift
+          end
+
+          rows = []
+          Textus::Hooks::Registry::EVENTS.each do |event, spec|
+            mode = spec[:mode].to_s
+            case spec[:mode]
+            when :rpc
+              store.registry.rpc_names(event).each do |name|
+                rows << { "event" => event.to_s, "mode" => mode, "name" => name.to_s }
+              end
+            when :pubsub
+              store.registry.pubsub_handlers(event).each do |h|
+                row = { "event" => event.to_s, "mode" => mode, "name" => h[:name].to_s }
+                row["keys"] = Array(h[:keys]) if h[:keys]
+                rows << row
+              end
+            end
+          end
+          store.manifest.entries.each do |e|
+            e.events.each do |evt, defs|
+              Array(defs).each do |defn|
+                next unless defn["exec"]
+
+                rows << {
+                  "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
+                  "key" => e.key, "as" => defn["as"] || "script"
+                }
+              end
+            end
+          end
+          rows.select! { |r| r["event"] == event_filter } if event_filter
+
+          emit({ "hooks" => rows })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class Init < Verb
+        def self.needs_store? = false
+
+        def call(_store)
+          target = File.join(@cwd, ".textus")
+          emit(Textus::Init.run(target))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Verb
+      class Intro < Verb
+        def call(store)
+          emit(Textus::Intro.run(store))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class List < Verb
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+
+        def call(store)
+          emit({ "entries" => store.list(prefix: prefix, zone: zone) })
+        end
+      end
+    end
+  end
+end