textus 0.52.0 → 0.54.0

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

@@ -1,9 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class Hook < Group
-        command_name "hook"
-      end
-    end
-  end
-end

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

@@ -1,9 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class Key < Group
-        command_name "key"
-      end
-    end
-  end
-end

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

@@ -1,9 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class MCP < Group
-        command_name "mcp"
-      end
-    end
-  end
-end

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

@@ -1,9 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class Rule < Group
-        command_name "rule"
-      end
-    end
-  end
-end

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

@@ -1,9 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class Schema < Group
-        command_name "schema"
-      end
-    end
-  end
-end

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

@@ -1,9 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class Zone < Group
-        command_name "zone"
-      end
-    end
-  end
-end

data/lib/textus/cli/group.rb

@@ -1,48 +0,0 @@
-module Textus
-  class CLI
-    class Group < Verb
-      class << self
-        # Subcommands are auto-derived: any Verb descendant whose
-        # `parent_group` is this group counts as a subcommand. Sorted
-        # alphabetically by command_name for stable help output.
-        def subcommands
-          Textus::CLI::Runner.install!
-          Verb.descendants
-              .select { |k| k.parent_group == self && k.command_name }
-              .sort_by(&:command_name)
-              .to_h { |k| [k.command_name, k] }
-        end
-
-        def needs_store?
-          # Delegate to the matched subcommand at parse time; default true.
-          true
-        end
-      end
-
-      def parse(argv)
-        subs = self.class.subcommands
-        subname = argv.shift
-        if subname.nil?
-          raise UsageError.new(
-            "#{self.class.command_name} requires a subcommand: #{subs.keys.join(", ")}",
-          )
-        end
-
-        @sub_klass = subs[subname]
-        unless @sub_klass
-          raise UsageError.new(
-            "unknown #{self.class.command_name} subcommand '#{subname}'. " \
-            "Valid: #{subs.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/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