textus 0.3.0 → 0.5.0

data/lib/textus/cli/schema_migrate.rb

@@ -0,0 +1,19 @@
+module Textus
+  class CLI
+    class SchemaMigrate < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "schema-migrate"
+      def self.replacement_path = "schema migrate"
+
+      option :rename, "--rename=O:N"
+
+      def call(store)
+        name = positional.shift or raise UsageError.new("schema-migrate NAME")
+        raise UsageError.new("schema-migrate requires --rename=OLD:NEW") unless rename
+
+        emit(Textus::SchemaTools.migrate(store, name: name, rename: rename))
+      end
+    end
+  end
+end

data/lib/textus/cli/stale.rb

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Stale < Verb
+      option :prefix, "--prefix=KEY"
+      option :zone, "--zone=Z"
+
+      def call(store)
+        emit(store.stale(prefix: prefix, zone: zone))
+      end
+    end
+  end
+end

data/lib/textus/cli/uid.rb

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class Uid < Verb
+      prepend DeprecatedAliasMixin
+
+      def self.deprecated_name = "uid"
+      def self.replacement_path = "key uid"
+
+      def call(store)
+        key = positional.shift or raise UsageError.new("uid requires a key")
+        emit({ "key" => key, "uid" => store.uid(key) })
+      end
+    end
+  end
+end

data/lib/textus/cli/verb.rb

@@ -0,0 +1,62 @@
+require "json"
+require "optparse"
+
+module Textus
+  class CLI
+    # Subclasses must implement #call(store) and return an integer exit code.
+    # Use #emit(obj) for normal JSON output (returns 0).
+    # Subclasses that don't need a Textus store (e.g. Init) override
+    # `.needs_store?` to return false; dispatch will pass nil instead.
+    class Verb
+      class << self
+        def option(name, optspec)
+          options << [name, optspec]
+          attr_accessor(name)
+        end
+
+        def options
+          @options ||= []
+        end
+
+        def needs_store?
+          true
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@options, [])
+        end
+      end
+
+      def initialize(stdin:, stdout:, stderr:, cwd: nil)
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @cwd = cwd
+      end
+
+      def parse(argv)
+        fmt = "json"
+        OptionParser.new do |o|
+          self.class.options.each do |name, optspec|
+            o.on(optspec) { |v| public_send(:"#{name}=", v) }
+          end
+          o.on("--format=FMT") { |v| fmt = v }
+        end.permute!(argv)
+        raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
+
+        @positional = argv.dup
+      end
+
+      attr_reader :positional
+
+      # Hashes get "protocol" => PROTOCOL prepended unless they already
+      # carry one (Store envelopes do). Caller's value wins on collision.
+      def emit(obj, exit_code: 0)
+        payload = obj.is_a?(Hash) ? { "protocol" => PROTOCOL }.merge(obj) : obj
+        @stdout.puts(JSON.generate(payload))
+        exit_code
+      end
+    end
+  end
+end

data/lib/textus/cli/where.rb

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

data/lib/textus/cli.rb

@@ -1,12 +1,45 @@
 require "json"
 require "optparse"
-require "time"
-require "timeout"
-require "yaml"
 
 module Textus
-  # rubocop:disable Metrics/ClassLength
   class CLI
+    # verb name → Verb subclass. Adding a new verb is a one-line entry here
+    # plus a new file under lib/textus/cli/.
+    VERBS = {
+      "accept" => Accept,
+      "action" => Action,
+      "build" => Build,
+      "delete" => Delete,
+      "deps" => Deps,
+      "doctor" => DoctorVerb,
+      "extension" => ExtensionGroup,
+      "extensions" => Extensions,
+      "get" => Get,
+      "init" => InitVerb,
+      "intro" => IntroVerb,
+      "key" => KeyGroup,
+      "list" => List,
+      "migrate" => Migrate,
+      "migrate-keys" => MigrateKeysVerb,
+      "mv" => Mv,
+      "published" => Published,
+      "put" => Put,
+      "rdeps" => Rdeps,
+      "refresh" => RefreshVerb,
+      "schema" => SchemaGroup,
+      "schema-diff" => SchemaDiff,
+      "schema-init" => SchemaInit,
+      "schema-migrate" => SchemaMigrate,
+      "stale" => Stale,
+      "uid" => Uid,
+      "where" => Where,
+    }.freeze
+
+    # Flat aliases kept for backward-compat through 0.5; emit deprecation warnings.
+    DEPRECATED_ALIASES = %w[
+      mv uid migrate-keys schema-init schema-diff schema-migrate extensions action
+    ].freeze
+
     def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
       new(stdin: stdin, stdout: stdout, stderr: stderr, cwd: cwd).run(argv)
     end
@@ -19,43 +52,19 @@ module Textus
       @root_arg = nil
     end
 
-    def run(argv) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize
-      OptionParser.new do |o|
-        o.on("--root=PATH") { |v| @root_arg = v }
-      end.order!(argv)
+    def run(argv)
+      OptionParser.new { |o| o.on("--root=PATH") { |v| @root_arg = v } }.order!(argv)
       verb = argv.shift
       raise UsageError.new("missing verb") if verb.nil?
 
       case verb
-      when "list"   then verb_list(argv)
-      when "where"  then verb_where(argv)
-      when "get"    then verb_get(argv)
-      when "put"    then verb_put(argv)
-      when "schema" then verb_schema(argv)
-      when "stale"  then verb_stale(argv)
-      when "delete"       then verb_delete(argv)
-      when "validate-all" then verb_validate_all(argv)
-      when "build"        then verb_build(argv)
-      when "deps"         then verb_deps(argv)
-      when "rdeps"        then verb_rdeps(argv)
-      when "published"    then verb_published(argv)
-      when "accept"       then verb_accept(argv)
-      when "init"         then verb_init(argv)
-      when "schema-init"    then verb_schema_init(argv)
-      when "schema-diff"    then verb_schema_diff(argv)
-      when "schema-migrate" then verb_schema_migrate(argv)
-      when "refresh"        then verb_refresh(argv)
-      when "extensions"     then verb_extensions(argv)
-      when "migrate-keys"   then verb_migrate_keys(argv)
-      when "mv"             then verb_mv(argv)
-      when "uid"            then verb_uid(argv)
-      when "doctor"         then verb_doctor(argv)
-      when "intro"          then verb_intro(argv)
       when "--version", "-v" then @stdout.puts(VERSION)
                                   0
       when "--help", "-h"    then print_help
                                   0
-      else raise UsageError.new("unknown verb: #{verb}")
+      else
+        klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
+        dispatch(klass, argv, deprecated_alias: DEPRECATED_ALIASES.include?(verb))
       end
     rescue Textus::Error => e
       emit_error(e)
@@ -67,310 +76,11 @@ module Textus
       @store ||= Store.discover(@cwd, root: @root_arg)
     end
 
-    def parse_format!(argv)
-      fmt = "text"
-      OptionParser.new do |o|
-        o.on("--format=FMT") { |v| fmt = v }
-      end.permute!(argv)
-      raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
-
-      fmt
-    end
-
-    def parse_prefix!(argv)
-      prefix = nil
-      OptionParser.new do |o|
-        o.on("--prefix=KEY") { |v| prefix = v }
-        o.on("--zone=Z") {}
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      prefix
-    end
-
-    def parse_prefix_and_zone!(argv)
-      prefix = nil
-      zone = nil
-      fmt = "text"
-      OptionParser.new do |o|
-        o.on("--prefix=KEY") { |v| prefix = v }
-        o.on("--zone=Z") { |v| zone = v }
-        o.on("--format=FMT") { |v| fmt = v }
-      end.permute!(argv)
-      raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
-
-      [prefix, zone]
-    end
-
-    def verb_list(argv)
-      prefix, zone = parse_prefix_and_zone!(argv)
-      emit({ "protocol" => PROTOCOL, "entries" => store.list(prefix: prefix, zone: zone) })
-    end
-
-    def verb_where(argv)
-      key = argv.shift or raise UsageError.new("where requires a key")
-      parse_format!(argv)
-      emit(store.where(key))
-    end
-
-    def verb_get(argv)
-      key = argv.shift or raise UsageError.new("get requires a key")
-      parse_format!(argv)
-      emit(store.get(key))
-    end
-
-    def verb_schema(argv)
-      key = argv.shift or raise UsageError.new("schema requires a key")
-      parse_format!(argv)
-      emit(store.schema_envelope(key))
-    end
-
-    def verb_stale(argv)
-      prefix, zone = parse_prefix_and_zone!(argv)
-      emit(store.stale(prefix: prefix, zone: zone))
-    end
-
-    def verb_put(argv) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      key = argv.shift or raise UsageError.new("put requires a key")
-      as_flag = nil
-      use_stdin = false
-      fetcher_name = nil
-      OptionParser.new do |o|
-        o.on("--stdin") { use_stdin = true }
-        o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--fetcher=NAME") { |v| fetcher_name = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      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 fetcher_name
-          callable = store.registry.fetcher(fetcher_name)
-          result =
-            begin
-              Timeout.timeout(Textus::Refresh::FETCHER_TIMEOUT_SECONDS) do
-                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store))
-              end
-            rescue Timeout::Error
-              raise UsageError.new(
-                "fetcher '#{fetcher_name}' exceeded #{Textus::Refresh::FETCHER_TIMEOUT_SECONDS}s timeout",
-              )
-            end
-          basename = key.split(".").last
-          {
-            "frontmatter" => {
-              "name" => basename,
-              "last_refreshed_at" => Time.now.utc.iso8601,
-              "fetched_with" => fetcher_name,
-            }.merge(result[:frontmatter] || result["frontmatter"] || {}),
-            "body" => result[:body] || result["body"] || "",
-          }
-        else
-          JSON.parse(raw)
-        end
-
-      fm = payload["frontmatter"] || {}
-      body = payload["body"] || ""
-      if_etag = payload["if_etag"]
-      emit(store.put(key, frontmatter: fm, body: body, if_etag: if_etag, as: role))
-    end
-
-    def verb_delete(argv)
-      key = argv.shift or raise UsageError.new("delete requires a key")
-      as_flag = nil
-      if_etag = nil
-      OptionParser.new do |o|
-        o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--if-etag=E") { |v| if_etag = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-      emit(store.delete(key, if_etag: if_etag, as: role))
-    end
-
-    def verb_validate_all(argv)
-      parse_format!(argv)
-      res = store.validate_all
-      @stdout.puts(JSON.generate(res))
-      res["ok"] ? 0 : 1
-    end
-
-    def verb_build(argv)
-      prefix = nil
-      OptionParser.new do |o|
-        o.on("--prefix=K") { |v| prefix = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      res = Textus::Builder.new(store).build(prefix: prefix)
-      @stdout.puts(JSON.generate(res))
-      0
-    end
-
-    def verb_deps(argv)
-      key = argv.shift or raise UsageError.new("deps requires a key")
-      parse_format!(argv)
-      emit({ "protocol" => Textus::PROTOCOL, "key" => key, "deps" => store.deps(key) })
-    end
-
-    def verb_rdeps(argv)
-      key = argv.shift or raise UsageError.new("rdeps requires a key")
-      parse_format!(argv)
-      emit({ "protocol" => Textus::PROTOCOL, "key" => key, "rdeps" => store.rdeps(key) })
-    end
-
-    def verb_schema_init(argv)
-      name = argv.shift or raise UsageError.new("schema-init NAME")
-      from_key = nil
-      OptionParser.new do |o|
-        o.on("--from=KEY") { |v| from_key = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      raise UsageError.new("schema-init requires --from=KEY") unless from_key
-
-      emit(Textus::SchemaTools.init(store, name: name, from: from_key))
-    end
-
-    def verb_schema_diff(argv)
-      name = argv.shift or raise UsageError.new("schema-diff NAME")
-      parse_format!(argv)
-      emit(Textus::SchemaTools.diff(store, name: name))
-    end
-
-    def verb_schema_migrate(argv)
-      name = argv.shift or raise UsageError.new("schema-migrate NAME")
-      rename = nil
-      OptionParser.new do |o|
-        o.on("--rename=O:N") { |v| rename = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      raise UsageError.new("schema-migrate requires --rename=OLD:NEW") unless rename
-
-      emit(Textus::SchemaTools.migrate(store, name: name, rename: rename))
-    end
-
-    def verb_init(argv)
-      OptionParser.new do |o|
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      target = File.join(@cwd, ".textus")
-      res = Textus::Init.run(target)
-      @stdout.puts(JSON.generate(res))
-      0
-    end
-
-    def verb_accept(argv)
-      key = argv.shift or raise UsageError.new("accept requires a key")
-      as_flag = nil
-      OptionParser.new do |o|
-        o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-      emit(store.accept(key, as: role))
-    end
-
-    def verb_refresh(argv)
-      key = argv.shift or raise UsageError.new("refresh requires a key")
-      as_flag = nil
-      OptionParser.new do |o|
-        o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-      emit(Textus::Refresh.call(store, key, as: role))
-    end
-
-    def verb_extensions(argv) # rubocop:disable Metrics/AbcSize
-      subcommand = argv.shift
-      raise UsageError.new("extensions requires 'list'") unless subcommand == "list"
-
-      kind = nil
-      OptionParser.new do |o|
-        o.on("--kind=K") { |v| kind = v }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-
-      rows = []
-      rows += store.registry.fetcher_names.map { |n| { "kind" => "fetcher", "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({ "protocol" => Textus::PROTOCOL, "extensions" => rows })
-    end
-
-    def verb_migrate_keys(argv)
-      write = false
-      OptionParser.new do |o|
-        o.on("--dry-run") { write = false }
-        o.on("--write")   { write = true }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      res = Textus::MigrateKeys.run(store, write: write)
-      @stdout.puts(JSON.generate(res))
-      res["ok"] ? 0 : 1
-    end
-
-    def verb_mv(argv)
-      old_key = argv.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-      new_key = argv.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-      as_flag = nil
-      dry_run = false
-      OptionParser.new do |o|
-        o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--dry-run") { dry_run = true }
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-      emit(store.mv(old_key, new_key, as: role, dry_run: dry_run))
-    end
-
-    def verb_uid(argv)
-      key = argv.shift or raise UsageError.new("uid requires a key")
-      parse_format!(argv)
-      emit({ "protocol" => PROTOCOL, "key" => key, "uid" => store.uid(key) })
-    end
-
-    def verb_intro(argv)
-      parse_format!(argv)
-      emit(Textus::Intro.run(store))
-    end
-
-    def verb_doctor(argv)
-      OptionParser.new do |o|
-        o.on("--format=FMT") {}
-      end.permute!(argv)
-      res = Textus::Doctor.run(store)
-      @stdout.puts(JSON.generate(res))
-      res["ok"] ? 0 : 1
-    end
-
-    def verb_published(argv)
-      parse_format!(argv)
-      emit({ "protocol" => Textus::PROTOCOL, "published" => store.published })
-    end
-
-    def emit(obj)
-      @stdout.puts(JSON.generate(obj))
-      0
+    def dispatch(klass, argv, deprecated_alias: false)
+      v = klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
+      v.deprecated_alias = true if deprecated_alias && v.respond_to?(:deprecated_alias=)
+      v.parse(argv)
+      v.call(klass.needs_store? ? store : nil)
     end
 
     def emit_error(err)
@@ -382,17 +92,25 @@ module Textus
 
     def print_help
       @stdout.puts <<~HELP
-        textus #{VERSION} — reference implementation of #{PROTOCOL}
-
-        Usage:
-          textus list [--prefix=KEY] --format=json
-          textus where KEY --format=json
-          textus get KEY --format=json
-          textus put KEY --stdin --format=json
-          textus schema KEY --format=json
-          textus stale [--prefix=KEY] --format=json
+        textus #{VERSION} — reference implementation of #{PROTOCOL} (was textus/1)
+
+        Usage (json output is the default; --format=json accepted for back-compat):
+          textus list [--prefix=KEY] [--zone=Z]
+          textus where KEY
+          textus get KEY
+          textus put KEY --stdin [--action=NAME] --as=ROLE
+          textus stale [--prefix=KEY] [--zone=Z]
+          textus doctor
+          textus intro
+          textus migrate v2
+
+          textus key {mv,uid,migrate}
+          textus schema {show,init,diff,migrate}
+          textus extension {list,run}
+
+        Deprecated (removed in 0.6): mv, uid, migrate-keys, schema-init,
+        schema-diff, schema-migrate, extensions, action.
       HELP
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end