textus 0.52.0 → 0.53.0

data/lib/textus/cli/runner.rb

@@ -1,193 +0,0 @@
-module Textus
-  class CLI
-    # Generates CLI::Verb (and CLI::Group) subclasses from per-verb contracts,
-    # so the CLI surface is a projection of the contract — the operator-facing
-    # mirror of MCP::Catalog (ADR 0063).
-    module Runner
-      # Subclassable base for contract-projected verbs. Carries the verb's
-      # contract (class attr `spec`) and the generic dispatch, exposing one
-      # overridable seam, #invoke, that defaults to the generic projection.
-      # Escape-hatch verbs subclass this and override #invoke to add behavior
-      # (suggestions, --stdin, BuildLock, multi-dispatch) WITHOUT restating the
-      # verb name — `spec.verb` remains the single source of dispatch.
-      class Base < Verb
-        class << self
-          attr_accessor :spec
-
-          # ADR 0064: derive the CLI command name from the contract's cli_leaf
-          # when not set explicitly, so an escape-hatch class never restates its
-          # own name. The reconciliation spec proves command_name == cli_leaf for
-          # every such class, so this is an equivalence, not a behavior change.
-          def command_name(name = nil)
-            return super if name
-
-            super() || spec&.cli_leaf
-          end
-        end
-
-        def spec = self.class.spec
-
-        def call(store)
-          invoke(store)
-        end
-
-        # Default: pure contract projection. Override in subclasses for behavior.
-        def invoke(store)
-          Runner.dispatch(self, store, spec)
-        end
-
-        def flag_values(s = spec)
-          s.args.reject(&:positional).each_with_object({}) do |a, h|
-            raw = respond_to?(a.name) ? public_send(a.name) : nil
-            next if raw.nil?
-
-            h[a.name] = Runner.coerce(a, raw)
-          end
-        end
-      end
-
-      module_function
-
-      # Normalize parsed CLI input into the uniform by-name inputs hash and
-      # dispatch through RoleScope's single bind+invoke site. A missing required
-      # arg becomes a UsageError phrased in the operator's command path (parity
-      # with the hand-written verbs).
-      def dispatch(verb_instance, store, spec)
-        inputs = Textus::Contract::Binder.inputs_from_ordered(
-          spec, verb_instance.positional, verb_instance.flag_values(spec)
-        )
-        inputs = inputs.merge(Textus::Contract::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
-        inputs = Textus::Contract::Sources.acquire(spec, inputs)
-        inputs = apply_cli_defaults(spec, inputs)
-        scope = verb_instance.session_for(store)
-        begin
-          result = scope.dispatch_bound(spec.verb, inputs)
-        rescue Textus::Contract::MissingArgs => e
-          raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
-        end
-        verb_instance.emit(shape(spec, result, inputs))
-      end
-
-      # Fill CLI-specific defaults (cli_default:) for args the operator did not
-      # pass, where the CLI default diverges from the contract default the agent
-      # surfaces use — e.g. migrate/zone_mv apply by default on the CLI but plan
-      # by default for agents (ADR 0068). The divergence is legible in the
-      # contract, not hidden in a hand class.
-      def apply_cli_defaults(spec, inputs)
-        spec.args.each_with_object(inputs.dup) do |a, h|
-          next if a.cli_default == :__unset || h.key?(a.name)
-
-          h[a.name] = a.cli_default
-        end
-      end
-
-      # Shape the use-case result for the CLI wire via the verb's :cli view
-      # (falling back to the default view). The view is called uniformly as
-      # (result, inputs); an inputs-aware view echoes an input such as the key
-      # (ADR 0067).
-      def shape(spec, result, inputs)
-        Textus::Contract::View.render(spec, :cli, result, inputs)
-      end
-
-      # The default the CLI flag is generated against — `cli_default:` when the
-      # operator-facing default diverges from the contract default the agent
-      # surfaces use, else the contract `default`. This drives boolean flag
-      # polarity so a verb that applies-by-default on the CLI but plans-by-default
-      # for agents (migrate, zone_mv) gets a `--dry-run` flag, not `--no-dry-run`.
-      def effective_default(arg)
-        arg.cli_default == :__unset ? arg.default : arg.cli_default
-      end
-
-      def flagspec_for(arg)
-        wire = arg.wire.to_s.tr("_", "-")
-        if arg.type == :boolean
-          effective_default(arg) == true ? "--no-#{wire}" : "--#{wire}"
-        else
-          "--#{wire}=VALUE"
-        end
-      end
-
-      # NB: compare arg.type by equality, not `case`/`===` — `Integer === arg.type`
-      # is false when arg.type is the Integer *class* (it tests instance-of), so a
-      # `when Integer` branch would silently never coerce.
-      def coerce(arg, raw)
-        return effective_default(arg) != true if arg.type == :boolean
-        return Integer(raw) if arg.type == Integer
-
-        raw
-      end
-
-      def ensure_group(name)
-        const = name.split("_").map(&:capitalize).join
-        return Group.const_get(const, false) if Group.const_defined?(const, false)
-
-        g = Class.new(Group) { command_name name }
-        Group.const_set(const, g)
-        g
-      end
-
-      # Contract verbs whose CLI behavior is a genuine `< Runner::Base` override
-      # — behavior the generic projection cannot express (ADR 0068/0069):
-      #   get   — raises UnknownKey with resolver suggestions (a CLI-only
-      #           affordance; the agent surface deliberately returns nil)
-      #   put   — reads the entry JSON from --stdin (ADR 0089: just stores bytes,
-      #           no --fetch transform)
-      # (build removed in ADR 0087: materialization is system-pushed via drain/serve)
-      BEHAVIORAL_HATCHES = %i[get put].freeze
-
-      # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
-      # all — composite reports assembled outside the contract.
-      # (boot removed: its contract carries surfaces :cli + the :lean arg, so the
-      # generic projection now generates it; the hand-authored CLI::Verb::Boot is
-      # deleted in ADR 0101.)
-      # (doctor retained: hand-authored to preserve --check=NAME flag spelling and
-      # the exit_code: res["ok"] ? 0 : 1 behavior — two things the generic
-      # projection cannot yet express; kept in ADR 0101 pending a future pass.)
-      # (fetch/fetch_all were removed in ADR 0079: Produce::Acquire::Intake is now internal,
-      # driven by the converge sweep (drain/serve) and hook run — ADR 0089 removed the
-      # read-through that once also drove it.)
-      NON_PROJECTED_CLI = %i[doctor].freeze
-
-      # The installer skips generation for either category.
-      HAND_AUTHORED_VERBS = (BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze
-
-      def hand_authored?(verb) = HAND_AUTHORED_VERBS.include?(verb)
-
-      def install!
-        @installed ||= {}
-        Textus::Dispatcher::VERBS.each_value do |klass|
-          next unless klass.respond_to?(:contract?) && klass.contract?
-
-          spec = klass.contract
-          next unless spec.cli?
-          next if hand_authored?(spec.verb)
-          next if @installed[spec.verb]
-
-          install_for(spec)
-          @installed[spec.verb] = true
-        end
-      end
-
-      def install_for(spec)
-        group = spec.cli_group ? ensure_group(spec.cli_group) : nil
-        leaf  = spec.cli_leaf
-        non_positional = spec.args.reject(&:positional)
-
-        klass = Class.new(Base)
-        klass.spec = spec
-        klass.command_name leaf
-        klass.parent_group group if group
-        klass.option :as_flag, "--as=ROLE"
-        klass.option :use_stdin, "--stdin" if spec.cli_stdin
-        non_positional.each { |a| klass.option a.name, Runner.flagspec_for(a) }
-
-        # Anchor the anonymous class to a constant so descendants discovery is
-        # stable. Name it after the verb under a Generated namespace.
-        const_name = spec.verb.to_s.split("_").map(&:capitalize).join
-        gen = "Gen#{const_name}"
-        Verb.const_set(gen, klass) unless Verb.const_defined?(gen, false)
-        klass
-      end
-    end
-  end
-end

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

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

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

@@ -1,18 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Get < Runner::Base
-        self.spec = Textus::Read::Get.contract
-        option :as_flag, "--as=ROLE"
-
-        def invoke(store)
-          key = positional.shift or raise UsageError.new("get requires a key")
-          result = session_for(store).get(key)
-          raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
-
-          emit(result.to_h_for_wire)
-        end
-      end
-    end
-  end
-end

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

@@ -1,48 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class HookRun < Verb
-        command_name "run"
-        parent_group Group::Hook
-
-        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--output=/           then next
-            when /\A--format=/           then raise FlagRenamed.new("--format", "--output")
-            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
-
-          # Validate --as resolves to a declared role (raises InvalidRole); hook
-          # run has no role-scoped authority itself, so the result is discarded.
-          Role.resolve(flag: as_flag, env: ENV, root: store.root)
-
-          begin
-            Textus::Produce::Acquire::Handler.invoke(
-              caps: store.container, handler: name, config: {}, args: args, label: "hook run",
-            )
-          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

@@ -1,50 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Hooks < Verb
-        command_name "list"
-        parent_group Group::Hook
-
-        option :event_filter, "--event=E"
-
-        def call(store) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-          subcommand = positional.first
-          if subcommand
-            raise UsageError.new("hook requires 'list'") unless subcommand == "list"
-
-            positional.shift
-          end
-
-          rows = []
-          Textus::Hooks::Catalog::RPC.each_key do |event|
-            store.rpc.names(event).each do |name|
-              rows << { "event" => event.to_s, "mode" => "rpc", "name" => name.to_s }
-            end
-          end
-          Textus::Hooks::Catalog::PUBSUB.each_key do |event|
-            store.events.pubsub_handlers(event).each do |h|
-              row = { "event" => event.to_s, "mode" => "pubsub", "name" => h[:name].to_s }
-              row["keys"] = Array(h[:keys]) if h[:keys]
-              rows << row
-            end
-          end
-          store.manifest.data.entries.each do |e|
-            (e.respond_to?(:events) ? 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"] || Textus::Role::AUTOMATION
-                }
-              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

@@ -1,18 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Init < Verb
-        command_name "init"
-
-        option :with_agent, "--with-agent"
-
-        def self.needs_store? = false
-
-        def call(_store)
-          target = File.join(@cwd, ".textus")
-          emit(Textus::Init.run(target, with_agent: !!with_agent))
-        end
-      end
-    end
-  end
-end

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

@@ -1,22 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      # Launches the MCP stdio server in the current process. Blocks on stdin;
-      # never returns until stdin closes. The connection acts as the `agent`
-      # role by default (ADR 0040): the agent channel proposes, it does not
-      # inherit the human's authority. Override per connection with --as, or
-      # TEXTUS_ROLE / .textus/role (same chain as every other verb).
-      class MCPServe < Verb
-        command_name "serve"
-        parent_group Group::MCP
-        option :as_flag, "--as=ROLE"
-
-        def call(store)
-          role = resolved_role(store, default: Textus::Role::AGENT)
-          Textus::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
-          0
-        end
-      end
-    end
-  end
-end

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

@@ -1,30 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Put < Runner::Base
-        self.spec = Textus::Write::Put.contract
-
-        option :as_flag, "--as=ROLE"
-        option :use_stdin, "--stdin"
-
-        def invoke(store)
-          key = positional.shift or raise UsageError.new("put requires a key")
-          raise UsageError.new("put requires --stdin in v1") unless use_stdin
-
-          role = resolved_role(store)
-
-          # put only stores the stdin JSON (ADR 0089): no transform-on-write.
-          # Ingest (running a handler over bytes) is system-pushed via drain/serve
-          # and hook run, never a put flag.
-          payload = JSON.parse(@stdin.read)
-
-          meta = payload["_meta"] || {}
-          body = payload["body"] || ""
-          if_etag = payload["if_etag"]
-          result = store.as(role).put(key, meta: meta, body: body, if_etag: if_etag)
-          emit(result.to_h_for_wire)
-        end
-      end
-    end
-  end
-end

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

@@ -1,15 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class SchemaDiff < Verb
-        command_name "diff"
-        parent_group Group::Schema
-
-        def call(store)
-          name = positional.shift or raise UsageError.new("schema diff NAME")
-          emit(Textus::Schema::Tools.diff(store, name: name))
-        end
-      end
-    end
-  end
-end

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

@@ -1,19 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class SchemaInit < Verb
-        command_name "init"
-        parent_group Group::Schema
-
-        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::Schema::Tools.init(store, name: name, from: from_key))
-        end
-      end
-    end
-  end
-end

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

@@ -1,19 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class SchemaMigrate < Verb
-        command_name "migrate"
-        parent_group Group::Schema
-
-        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::Schema::Tools.migrate(store, name: name, rename: rename))
-        end
-      end
-    end
-  end
-end

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

@@ -1,19 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      # Launches the convergence daemon in the current process. Blocks forever;
-      # reclaims crashed leases and drains the queue each tick (Phase 3 adds
-      # scheduled TTL re-pull/sweep). CLI-only — agents enqueue work, they do not
-      # run daemons. Acts as the automation role (the build authority).
-      class Serve < Verb
-        command_name "serve"
-
-        def call(store)
-          call = Textus::Call.build(role: Textus::Role::AUTOMATION)
-          Textus::Maintenance::Serve.new(container: store.container, call: call).run
-          0
-        end
-      end
-    end
-  end
-end

data/lib/textus/cli/verb.rb

@@ -1,116 +0,0 @@
-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
-
-        # Declarative CLI name. Reader returns the registered name (or nil
-        # for verbs that aren't directly invokable, like the abstract
-        # Verb/Group base classes). Writer registers it.
-        def command_name(name = nil)
-          if name.nil?
-            @command_name
-          else
-            @command_name = name.to_s
-          end
-        end
-
-        # Declares that this verb is a subcommand of `group_klass`. When
-        # set, the verb is NOT a top-level CLI verb — it's listed under
-        # the group's subcommands instead.
-        def parent_group(group_klass = nil)
-          if group_klass.nil?
-            @parent_group
-          else
-            @parent_group = group_klass
-          end
-        end
-
-        def inherited(subclass)
-          super
-          subclass.instance_variable_set(:@options, [])
-          subclass.instance_variable_set(:@command_name, nil)
-          subclass.instance_variable_set(:@parent_group, nil)
-        end
-
-        # Recursive subclass enumeration. Ruby 3.1 ships Class#subclasses
-        # but not Class#descendants, so we expand it ourselves.
-        def descendants
-          subclasses.flat_map { |k| [k] + k.descendants }
-        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("--output=FMT") { |v| fmt = v }
-          o.on("--format=FMT") { |_v| raise FlagRenamed.new("--format", "--output") }
-        end.permute!(argv)
-        raise UsageError.new("only --output=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
-
-      # Resolves the active role for this invocation. Honors the verb's
-      # `--as` flag if declared, then TEXTUS_ROLE, then the project default.
-      # Pass `default:` to override the fallback (e.g. MCPServe uses AGENT).
-      def resolved_role(store, default: Role::DEFAULT)
-        flag = respond_to?(:as_flag) ? as_flag : nil
-        Role.resolve(flag: flag, env: ENV, root: store.root, default: default)
-      end
-
-      # Returns a Call value bound to the resolved role. Convenience for
-      # verbs whose only pre-call boilerplate is resolving the role and
-      # wrapping it in a Call.
-      def context_for(store)
-        Textus::Call.build(role: resolved_role(store))
-      end
-
-      # Returns a RoleScope bound to the resolved role.
-      def session_for(store)
-        store.as(resolved_role(store))
-      end
-
-      # The input stream — the source for a `cli_stdin` envelope (ADR 0068).
-      attr_reader :stdin
-    end
-  end
-end