textus 0.52.0 → 0.53.0

data/lib/textus/step/validate.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Textus
+  module Step
+    # Checks an artifact/store state and returns diagnostics. Replaces the
+    # :validate RPC. Receives only `caps:` (injected by the registry).
+    class Validate < Base
+      def self.required_kwargs = []
+    end
+  end
+end

data/lib/textus/step.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Textus
+  # A Step is a unit of user-extensible behaviour discovered by convention at
+  # .textus/steps/<kind>/<name>.rb. Five kinds: fetch (external acquisition),
+  # transform (combine/reshape into an artifact), validate (check an artifact),
+  # observe (react to a lifecycle event). Replaces the Textus.hook block queue.
+  module Step
+  end
+end

data/lib/textus/store.rb

@@ -45,7 +45,8 @@ module Textus
     def initialize(root)
       @container = build_container(File.expand_path(root))
       bootstrap_hooks
-      events.publish(:store_loaded, ctx: Hooks::Context.new(scope: as(Role::DEFAULT)))
+      steps.publish(:store_loaded, ctx: Step::Context.for(container: @container,
+                                                          call: Textus::Call.build(role: Role::DEFAULT)))
     end
 
     # Build an agent Session oriented at the current cursor/manifest — the
@@ -54,26 +55,24 @@ module Textus
       Textus::Session.new(
         role: role,
         cursor: audit_log.latest_seq,
-        propose_zone: manifest.policy.propose_zone_for(role),
+        propose_lane: manifest.policy.propose_lane_for(role),
         contract_etag: Textus::Etag.for_contract(root),
       )
     end
 
-    def as(role, dry_run: false, correlation_id: nil)
-      RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
+    def gate
+      @container.gate
     end
 
-    Textus::Dispatcher::VERBS.each_key do |verb|
-      define_method(verb) do |*args, role: Role::DEFAULT, **kwargs|
-        as(role).public_send(verb, *args, **kwargs)
-      end
+    def as(role, dry_run: false, correlation_id: nil)
+      Textus::Surfaces::RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
     end
 
     private
 
     def build_container(root)
       manifest = Manifest.load(root)
-      Container.new(
+      container = Container.new(
         root: root,
         manifest: manifest,
         schemas: Schemas.new(File.join(root, "schemas")),
@@ -83,16 +82,19 @@ module Textus
           max_size: manifest.data.audit_config[:max_size],
           keep: manifest.data.audit_config[:keep],
         ),
-        events: Hooks::EventBus.new,
-        rpc: Hooks::RpcRegistry.new,
+        steps: Textus::Step::RegistryStore.new,
+        gate: nil,
       )
+      gate = Textus::Gate.new(container)
+      container = container.with(gate: gate)
+      gate.instance_variable_set(:@container, container)
+      container
     end
 
     def bootstrap_hooks
-      Ports::AuditSubscriber.new(audit_log).attach(events)
-      Ports::ProduceOnWriteSubscriber.new(container).attach(events)
-      Hooks::Builtin.register_all(events: events, rpc: rpc)
-      Hooks::Loader.new(events: events, rpc: rpc).load_dir(File.join(root, "hooks"))
+      Ports::AuditSubscriber.new(audit_log).attach(steps)
+      Textus::Step::Builtin.register_all(steps)
+      Textus::Step::Loader.new(registry: steps).load_dir(File.join(root, "steps"))
     end
   end
 end

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

@@ -0,0 +1,11 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group
+        class Data < Group
+          command_name "data"
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,50 @@
+module Textus
+  module Surfaces
+    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::Surfaces::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
+end

data/lib/textus/surfaces/cli/runner.rb

@@ -0,0 +1,236 @@
+module Textus
+  module Surfaces
+    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
+
+        # Build a Command from the spec + parsed inputs, dispatch through Gate.
+        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)
+          role = verb_instance.resolved_role(store)
+
+          invoke = lambda do |effective_inputs|
+            cmd = build_command(spec, effective_inputs, role)
+            store.gate.dispatch(cmd)
+          end
+
+          result = if spec.around
+                     scope = store.as(role)
+                     Textus::Contract::Around.with(spec.around, scope: scope, inputs: inputs, session: nil, &invoke)
+                   else
+                     invoke.call(inputs)
+                   end
+          verb_instance.emit(shape(spec, result, inputs))
+        rescue Textus::Contract::MissingArgs => e
+          raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
+        end
+
+        def build_command(spec, inputs, role)
+          cmd_class = Textus::Gate::VERB_COMMAND.fetch(spec.verb) do
+            raise Textus::UsageError.new("no Command for verb: #{spec.verb}")
+          end
+          defaults = {}
+          spec.args.each do |a|
+            next if a.default == :__unset || inputs.key?(a.name)
+            next if a.default.nil? && a.required
+
+            defaults[a.name] = a.default
+          end
+          kwargs = defaults.merge(inputs)
+          kwargs[:role] = role if cmd_class.members.include?(:role) && !inputs.key?(:role) && spec.verb != :audit
+          check_missing_args!(spec, cmd_class, kwargs)
+
+          cmd_class.new(**kwargs.slice(*cmd_class.members))
+        end
+
+        def check_missing_args!(spec, cmd_class, kwargs)
+          params = cmd_class.instance_method(:initialize).parameters
+          required = if params == [[:rest]]
+                       cmd_class.members
+                     else
+                       params.select { |t,| t == :keyreq }.map(&:last)
+                     end
+          missing = required - kwargs.keys
+          return if missing.empty?
+
+          raise Textus::Contract::MissingArgs.new(spec, missing.map { |m| Struct.new(:wire, :name).new(m.to_s, m) })
+        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/data_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, data_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::Gate::ROUTES.each_key do |cmd_class|
+            verb = Textus::Gate::VERB_COMMAND.key(cmd_class)
+            next unless verb
+
+            action_class = Textus::Gate::ROUTES[cmd_class].first
+            next unless action_class.respond_to?(:contract?) && action_class.contract?
+
+            spec = action_class.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
+end

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

@@ -0,0 +1,21 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Verb
+        class Doctor < Verb
+          command_name "doctor"
+          option :checks, "--check=NAME"
+
+          def call(store)
+            cmd = Textus::Command::Doctor.new(
+              checks: checks&.split(",")&.map(&:strip),
+              role: resolved_role(store),
+            )
+            res = store.gate.dispatch(cmd)
+            emit(res, exit_code: res["ok"] ? 0 : 1)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Verb
+        class Get < Runner::Base
+          self.spec = Textus::Action::Get.contract
+          option :as_flag, "--as=ROLE"
+
+          def invoke(store)
+            key = positional.shift or raise UsageError.new("get requires a key")
+            cmd = Textus::Command::Get.new(key: key, role: resolved_role(store))
+            result = store.gate.dispatch(cmd)
+            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
+end

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

@@ -0,0 +1,20 @@
+module Textus
+  module Surfaces
+    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
+end

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

@@ -0,0 +1,24 @@
+module Textus
+  module Surfaces
+    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::Surfaces::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
+            0
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Verb
+        class Put < Runner::Base
+          self.spec = Textus::Action::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
+
+            payload = JSON.parse(@stdin.read)
+            cmd = Textus::Command::Put.new(
+              key: key,
+              meta: payload["_meta"] || {},
+              body: payload["body"] || "",
+              content: nil,
+              if_etag: payload["if_etag"],
+              role: resolved_role(store),
+            )
+            result = store.gate.dispatch(cmd)
+            emit(result.to_h_for_wire)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Textus
+  module Surfaces
+    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
+end

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

@@ -0,0 +1,21 @@
+module Textus
+  module Surfaces
+    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
+end

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

@@ -0,0 +1,21 @@
+module Textus
+  module Surfaces
+    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
+end

data/lib/textus/surfaces/cli/verb/watch.rb

@@ -0,0 +1,19 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Verb
+        class Watch < Verb
+          command_name "watch"
+          option :as_flag, "--as=ROLE"
+          option :poll, "--poll=SECONDS"
+
+          def call(store)
+            watcher = Textus::Surfaces::Watcher.new(container: store.container)
+            watcher.run(poll: poll&.to_f)
+            0
+          end
+        end
+      end
+    end
+  end
+end