textus 0.3.0 → 0.5.0

data/lib/textus/builder.rb

@@ -96,14 +96,14 @@ module Textus
           "from" => Array(mentry.projection&.fetch("select", nil)).compact,
         },
       }
-      Entry.for_format("markdown").serialize(frontmatter: frontmatter, body: body)
+      Entry.for_format("markdown").serialize(meta: 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)
+      Entry.for_format("text").serialize(meta: {}, body: body)
     end
 
     # JSON / YAML pipeline. Templateless = default; template = escape hatch.
@@ -127,7 +127,7 @@ module Textus
         end
 
       final = inject_meta(content, mentry)
-      strategy.serialize(frontmatter: {}, body: "", content: final)
+      strategy.serialize(meta: {}, body: "", content: final)
     end
 
     def render_template!(mentry, data)

data/lib/textus/{builtin_fetchers.rb → builtin_actions.rb}

@@ -4,31 +4,35 @@ require "yaml"
 require "rexml/document"
 
 module Textus
-  module BuiltinFetchers
+  module BuiltinActions
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def self.register_all
-      Textus.fetcher(:json) do |config:, store:|
+      Textus.action(:json) do |config:, store:, args:|
         _ = store
+        _ = args
         data = JSON.parse(config["bytes"].to_s)
-        { frontmatter: {}, body: YAML.dump(data) }
+        { _meta: {}, body: YAML.dump(data) }
       end
 
-      Textus.fetcher(:csv) do |config:, store:|
+      Textus.action(:csv) do |config:, store:, args:|
         _ = store
+        _ = args
         rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
-        { frontmatter: {}, body: YAML.dump(rows) }
+        { _meta: {}, body: YAML.dump(rows) }
       end
 
-      Textus.fetcher(:"markdown-links") do |config:, store:|
+      Textus.action(:"markdown-links") do |config:, store:, args:|
         _ = store
+        _ = args
         links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
           { "text" => text, "href" => href }
         end
-        { frontmatter: {}, body: YAML.dump(links) }
+        { _meta: {}, body: YAML.dump(links) }
       end
 
-      Textus.fetcher(:"ical-events") do |config:, store:|
+      Textus.action(:"ical-events") do |config:, store:, args:|
         _ = store
+        _ = args
         events = []
         current = nil
         config["bytes"].to_s.each_line do |line|
@@ -42,11 +46,12 @@ module Textus
             current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
           end
         end
-        { frontmatter: {}, body: YAML.dump(events) }
+        { _meta: {}, body: YAML.dump(events) }
       end
 
-      Textus.fetcher(:rss) do |config:, store:|
+      Textus.action(:rss) do |config:, store:, args:|
         _ = store
+        _ = args
         doc = REXML::Document.new(config["bytes"].to_s)
         items = doc.elements.to_a("//item").map do |item|
           {
@@ -55,7 +60,7 @@ module Textus
             "pubDate" => item.elements["pubDate"]&.text,
           }
         end
-        { frontmatter: {}, body: YAML.dump(items) }
+        { _meta: {}, body: YAML.dump(items) }
       end
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength

data/lib/textus/cli/accept.rb

@@ -0,0 +1,13 @@
+module Textus
+  class CLI
+    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

data/lib/textus/cli/action.rb

@@ -0,0 +1,51 @@
+module Textus
+  class CLI
+    class Action < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "action"
+      def self.replacement_path = "extension run"
+
+      def parse(argv)
+        @raw_argv = argv
+      end
+
+      def call(store)
+        name = @raw_argv.shift
+        raise UsageError.new("action 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 'action #{name}': #{tok}")
+          end
+        end
+
+        role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+        callable = store.registry.action(name)
+        view = StoreView.new(store, writable: true, as: role)
+
+        begin
+          Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+            callable.call(config: {}, store: view, args: args)
+          end
+        rescue Timeout::Error
+          raise UsageError.new(
+            "action '#{name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
+          )
+        rescue Textus::Error
+          raise
+        rescue StandardError => e
+          raise UsageError.new("action '#{name}' raised: #{e.class}: #{e.message}")
+        end
+
+        emit({ "action" => name, "ok" => true })
+      end
+    end
+  end
+end

data/lib/textus/cli/build.rb

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

data/lib/textus/cli/delete.rb

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    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

data/lib/textus/cli/deprecated_alias.rb

@@ -0,0 +1,31 @@
+module Textus
+  class CLI
+    module DeprecatedAliasMixin
+      def self.prepended(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def deprecated_name
+          raise NotImplementedError.new("#{self}.deprecated_name must be defined")
+        end
+
+        def replacement_path
+          raise NotImplementedError.new("#{self}.replacement_path must be defined")
+        end
+      end
+
+      attr_writer :deprecated_alias
+
+      def call(store)
+        if @deprecated_alias
+          @stderr.puts(
+            "textus: '#{self.class.deprecated_name}' is deprecated; " \
+            "use 'textus #{self.class.replacement_path}' instead. Removed in 0.6.",
+          )
+        end
+        super
+      end
+    end
+  end
+end

data/lib/textus/cli/deps.rb

@@ -0,0 +1,10 @@
+module Textus
+  class CLI
+    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

data/lib/textus/cli/doctor.rb

@@ -0,0 +1,13 @@
+module Textus
+  class CLI
+    class DoctorVerb < 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

data/lib/textus/cli/extension_group.rb

@@ -0,0 +1,9 @@
+module Textus
+  class CLI
+    class ExtensionGroup < Group
+      self.cli_name = "extension"
+      subcommands["list"] = Extensions
+      subcommands["run"]  = Action
+    end
+  end
+end

data/lib/textus/cli/extensions.rb

@@ -0,0 +1,49 @@
+module Textus
+  class CLI
+    class Extensions < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "extensions"
+      def self.replacement_path = "extension list"
+
+      option :kind, "--kind=K"
+
+      def call(store) # rubocop:disable Metrics/AbcSize
+        # When invoked as the flat alias `textus extensions list`, the positional "list"
+        # is still present. When invoked via `textus extension list` (group), it has been
+        # consumed by the group dispatcher — both are valid.
+        subcommand = positional.first
+        if subcommand
+          raise UsageError.new("extensions requires 'list'") unless subcommand == "list"
+
+          positional.shift
+        end
+
+        rows = []
+        rows += store.registry.action_names.map { |n| { "kind" => "action", "name" => n.to_s } }
+        rows += store.registry.doctor_check_names.map { |n| { "kind" => "doctor_check", "name" => n.to_s } }
+        rows += store.registry.reducer_names.map { |n| { "kind" => "reducer", "name" => n.to_s } }
+        store.registry.hook_events.each do |evt|
+          store.registry.hooks(evt).each do |h|
+            rows << { "kind" => "hook", "event" => evt.to_s, "name" => h[:name].to_s }
+          end
+        end
+        store.manifest.entries.each do |e|
+          e.events.each do |evt, defs|
+            Array(defs).each do |defn|
+              next unless defn["exec"]
+
+              rows << {
+                "kind" => "hook", "event" => evt.to_s, "exec" => defn["exec"],
+                "key" => e.key, "as" => defn["as"] || "script"
+              }
+            end
+          end
+        end
+        rows.select! { |r| r["kind"] == kind } if kind
+
+        emit({ "extensions" => rows })
+      end
+    end
+  end
+end

data/lib/textus/cli/get.rb

@@ -0,0 +1,10 @@
+module Textus
+  class CLI
+    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

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/init.rb

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

data/lib/textus/cli/intro.rb

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

data/lib/textus/cli/key_group.rb

@@ -0,0 +1,10 @@
+module Textus
+  class CLI
+    class KeyGroup < Group
+      self.cli_name = "key"
+      subcommands["mv"]      = Mv
+      subcommands["uid"]     = Uid
+      subcommands["migrate"] = MigrateKeysVerb
+    end
+  end
+end

data/lib/textus/cli/list.rb

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    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

data/lib/textus/cli/migrate.rb

@@ -0,0 +1,41 @@
+module Textus
+  class CLI
+    class Migrate < Verb
+      # Does not need a store — the target manifest may still be textus/1.
+      def self.needs_store? = false
+
+      def call(_store)
+        target = positional.shift or raise UsageError.new("migrate requires a target (e.g. 'v2')")
+        raise UsageError.new("unknown migration target: #{target.inspect}; supported: v2") unless target == "v2"
+
+        # Locate the .textus directory the same way Store.discover does.
+        root = find_textus_root
+        emit(Textus::MigrateV2.run(root))
+      end
+
+      private
+
+      def find_textus_root
+        explicit = ENV.fetch("TEXTUS_ROOT", nil)
+        if explicit
+          abs = File.expand_path(explicit)
+          return abs if File.directory?(abs)
+
+          raise IoError.new("no textus store at #{abs}")
+        end
+
+        dir = File.expand_path(@cwd)
+        loop do
+          candidate = File.join(dir, ".textus")
+          return candidate if File.directory?(candidate) && File.exist?(File.join(candidate, "manifest.yaml"))
+
+          parent = File.dirname(dir)
+          break if parent == dir
+
+          dir = parent
+        end
+        raise IoError.new("no .textus directory found from #{@cwd}")
+      end
+    end
+  end
+end

data/lib/textus/cli/migrate_keys.rb

@@ -0,0 +1,19 @@
+module Textus
+  class CLI
+    class MigrateKeysVerb < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "migrate-keys"
+      def self.replacement_path = "key migrate"
+
+      option :write, "--write"
+      option :dry_run, "--dry-run"
+
+      def call(store)
+        effective_write = write && !dry_run
+        res = Textus::MigrateKeys.run(store, write: effective_write || false)
+        emit(res, exit_code: res["ok"] ? 0 : 1)
+      end
+    end
+  end
+end

data/lib/textus/cli/mv.rb

@@ -0,0 +1,20 @@
+module Textus
+  class CLI
+    class Mv < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "mv"
+      def self.replacement_path = "key mv"
+
+      option :as_flag, "--as=ROLE"
+      option :dry_run, "--dry-run"
+
+      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))
+      end
+    end
+  end
+end

data/lib/textus/cli/published.rb

@@ -0,0 +1,9 @@
+module Textus
+  class CLI
+    class Published < Verb
+      def call(store)
+        emit({ "published" => store.published })
+      end
+    end
+  end
+end

data/lib/textus/cli/put.rb

@@ -0,0 +1,48 @@
+module Textus
+  class CLI
+    class Put < Verb
+      option :as_flag, "--as=ROLE"
+      option :use_stdin, "--stdin"
+      option :action_name, "--action=NAME"
+
+      def call(store) # rubocop:disable Metrics/AbcSize
+        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)
+
+        raw = @stdin.read
+        payload =
+          if action_name
+            callable = store.registry.action(action_name)
+            result =
+              begin
+                Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+                  callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store), args: {})
+                end
+              rescue Timeout::Error
+                raise UsageError.new(
+                  "action '#{action_name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
+                )
+              end
+            basename = key.split(".").last
+            {
+              "_meta" => {
+                "name" => basename,
+                "last_refreshed_at" => Time.now.utc.iso8601,
+                "actioned_with" => action_name,
+              }.merge(result[:_meta] || result["_meta"] || result[:frontmatter] || result["frontmatter"] || {}),
+              "body" => result[:body] || result["body"] || "",
+            }
+          else
+            JSON.parse(raw)
+          end
+
+        meta = payload["_meta"] || payload["frontmatter"] || {}
+        body = payload["body"] || ""
+        if_etag = payload["if_etag"]
+        emit(store.put(key, meta: meta, body: body, if_etag: if_etag, as: role))
+      end
+    end
+  end
+end

data/lib/textus/cli/rdeps.rb

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

data/lib/textus/cli/refresh.rb

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

data/lib/textus/cli/schema.rb

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

data/lib/textus/cli/schema_diff.rb

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class SchemaDiff < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "schema-diff"
+      def self.replacement_path = "schema diff"
+
+      def call(store)
+        name = positional.shift or raise UsageError.new("schema-diff NAME")
+        emit(Textus::SchemaTools.diff(store, name: name))
+      end
+    end
+  end
+end

data/lib/textus/cli/schema_group.rb

@@ -0,0 +1,33 @@
+module Textus
+  class CLI
+    class SchemaGroup < Group
+      self.cli_name = "schema"
+      subcommands["show"]    = SchemaVerb
+      subcommands["init"]    = SchemaInit
+      subcommands["diff"]    = SchemaDiff
+      subcommands["migrate"] = SchemaMigrate
+
+      # Back-compat: `textus schema KEY` (dotted key, no subcommand word).
+      # If the first positional looks like a dotted key, treat it as `schema show KEY`.
+      def parse(argv)
+        first = argv.first
+        if first && dotted_key?(first)
+          @stderr.puts(
+            "textus: 'schema KEY' is deprecated; use 'textus schema show KEY' instead. Removed in 0.6.",
+          )
+          argv.unshift("show")
+        end
+        super
+      end
+
+      private
+
+      def dotted_key?(token)
+        return false if token.start_with?("-")
+        return false unless token.include?(".")
+
+        token.split(".").all? { |seg| seg.match?(Manifest::KEY_SEGMENT) }
+      end
+    end
+  end
+end

data/lib/textus/cli/schema_init.rb

@@ -0,0 +1,19 @@
+module Textus
+  class CLI
+    class SchemaInit < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "schema-init"
+      def self.replacement_path = "schema init"
+
+      option :from_key, "--from=KEY"
+
+      def call(store)
+        name = positional.shift or raise UsageError.new("schema-init NAME")
+        raise UsageError.new("schema-init requires --from=KEY") unless from_key
+
+        emit(Textus::SchemaTools.init(store, name: name, from: from_key))
+      end
+    end
+  end
+end