textus 0.52.0 → 0.53.0

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

@@ -0,0 +1,111 @@
+require "json"
+require "optparse"
+
+module Textus
+  module Surfaces
+    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
+
+        # Builds a Command from spec + inputs and dispatches through Gate.
+        def gate_dispatch(cmd, store)
+          store.gate.dispatch(cmd)
+        end
+
+        # The input stream — the source for a `cli_stdin` envelope (ADR 0068).
+        attr_reader :stdin
+      end
+    end
+  end
+end

data/lib/textus/surfaces/cli.rb

@@ -0,0 +1,148 @@
+require "json"
+require "optparse"
+
+module Textus
+  module Surfaces
+    class CLI
+      # Auto-derived verb table. Every CLI::Verb (or Group) subclass that
+      # declares `command_name "X"` and has no `parent_group` is a top-level
+      # verb. Sorted alphabetically for stable help output. Adding a new
+      # verb requires only a new file declaring its `command_name`.
+      #
+      # `k.name` gates out anonymous (Class.new) subclasses: real verbs are always
+      # named constants (generated Gen* or hand-authored classes), so this is a
+      # no-op in production but keeps throwaway test fixtures from leaking into the
+      # registry (and tripping the reconciliation guards order-dependently).
+      def self.verbs
+        Runner.install!
+        Verb.descendants
+            .select { |k| k.name && k.command_name && k.parent_group.nil? }
+            .sort_by(&:command_name)
+            .to_h { |k| [k.command_name, k] }
+      end
+
+      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
+
+      def initialize(stdin:, stdout:, stderr:, cwd:)
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @cwd = cwd
+        @root_arg = nil
+      end
+
+      def run(argv)
+        # `--root` is a global, position-agnostic option: pull it out of argv
+        # wherever it appears so it works uniformly before OR after any verb or
+        # group (e.g. both `textus --root=X hook list` and
+        # `textus hook list --root=X`). Without this, `order!` below only sees
+        # options before the first verb token, so a trailing `--root` reached the
+        # verb's own parser and raised InvalidOption (#161 F5). TEXTUS_ROOT already
+        # works everywhere via Store.discover, so this brings the flag to parity.
+        @root_arg = extract_root!(argv)
+
+        # Define --version/--help ourselves so OptionParser doesn't intercept them
+        # with its built-in handlers (which print "version unknown" and a bare usage
+        # line, then exit before we ever reach the verb dispatch below).
+        show_version = false
+        show_help = false
+        OptionParser.new do |o|
+          o.on("--version", "-v") { show_version = true }
+          o.on("--help", "-h") { show_help = true }
+        end.order!(argv)
+
+        return @stdout.puts(VERSION) || 0 if show_version
+        return print_help || 0 if show_help
+
+        verb = argv.shift
+        raise UsageError.new("missing verb") if verb.nil?
+
+        klass = self.class.verbs[verb] or raise UsageError.new("unknown verb: #{verb}")
+        coerce_exit_code(dispatch(klass, argv))
+      rescue Textus::Error => e
+        emit_error(e)
+      end
+
+      private
+
+      # Remove the first `--root=PATH` or `--root PATH` token from argv (anywhere)
+      # and return its value, or nil if absent. Mutates argv in place.
+      def extract_root!(argv)
+        i = argv.index { |a| a == "--root" || a.start_with?("--root=") }
+        return nil unless i
+
+        tok = argv[i]
+        if tok.start_with?("--root=")
+          argv.delete_at(i)
+          tok.delete_prefix("--root=")
+        else
+          val = argv[i + 1]
+          raise UsageError.new("--root requires a PATH") if val.nil? || val.start_with?("-")
+
+          argv.delete_at(i + 1)
+          argv.delete_at(i)
+          val
+        end
+      end
+
+      def coerce_exit_code(value)
+        case value
+        when Integer then value
+        when true, nil then 0
+        when false then 1
+        else
+          @stderr.puts("warning: verb returned non-Integer #{value.class}; treating as 0")
+          0
+        end
+      end
+
+      def store
+        @store ||= Store.discover(@cwd, root: @root_arg)
+      end
+
+      def dispatch(klass, argv)
+        v = klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
+        v.parse(argv)
+        v.call(klass.needs_store? ? store : nil)
+      end
+
+      def emit_error(err)
+        @stdout.puts(JSON.generate(err.to_envelope))
+        @stderr.puts("#{err.code}: #{err.message}")
+        @stderr.puts("  → #{err.hint}") if err.hint
+        err.exit_code
+      end
+
+      def print_help
+        @stdout.puts <<~HELP
+          textus #{VERSION} — reference implementation of #{PROTOCOL}
+
+          Usage (json output is the default):
+            textus list [--prefix=KEY] [--lane=LANE]
+            textus where KEY
+            textus get KEY
+            textus put KEY --stdin --as=ROLE
+            textus propose KEY --stdin --as=ROLE
+            textus accept KEY --as=ROLE
+            textus reject KEY --as=ROLE
+            textus audit [--key=K] [--lane=LANE] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
+            textus blame KEY [--limit=N]
+            textus pulse [--since=N]
+            textus boot
+            textus doctor
+            textus drain [PREFIX] --as=ROLE
+            textus watch
+            textus jobs
+
+            textus key {delete,mv,mv-prefix,delete-prefix,uid}
+            textus rule {explain,lint,list}
+            textus schema {diff,init,migrate,show}
+            textus data {mv}
+            textus mcp {serve}
+        HELP
+      end
+    end
+  end
+end

data/lib/textus/surfaces/mcp/catalog.rb

@@ -0,0 +1,99 @@
+module Textus
+  module Surfaces
+    module MCP
+      # Derives the entire MCP tool surface from the per-verb contracts
+      # (ADR 0039). `tool_schemas` feeds tools/list; `call` is the generic
+      # tools/call dispatch: map JSON args -> (positional, keyword) per the
+      # contract, invoke the verb through the role scope, then shape the
+      # return value with the contract's default view. No per-tool code.
+      module Catalog
+        module_function
+
+        WRITE_VERBS = %i[
+          put propose key_delete key_mv accept reject enqueue
+        ].freeze
+
+        MAINTENANCE_VERBS = %i[
+          data_mv key_mv_prefix key_delete_prefix drain rule_lint
+        ].freeze
+
+        # Contracts of every MCP-surfaced verb, in Dispatcher order.
+        def specs
+          Textus::Action::VERBS.values
+                               .select { |k| mcp_surfaced?(k) }
+                               .map(&:contract)
+        end
+
+        def tool_schemas
+          specs.map do |s|
+            { name: s.verb.to_s, description: s.summary, inputSchema: s.input_schema }
+          end.freeze
+        end
+
+        def names
+          specs.map { |s| s.verb.to_s }
+        end
+
+        # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
+        # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
+        # from this so it can never advertise a verb the agent cannot call, nor
+        # omit one it can (ADR 0056). Excludes write/maintenance verbs by verb
+        # identity (routing may be legacy UseCases or Dispatch::Actions).
+        def read_verbs
+          Textus::Action::VERBS
+            .reject { |verb, _klass| WRITE_VERBS.include?(verb) || MAINTENANCE_VERBS.include?(verb) }
+            .select { |_verb, klass| mcp_surfaced?(klass) }
+            .keys.map(&:to_s)
+        end
+
+        # MCP-surfaced write verbs, by Dispatcher class namespace — the mirror of
+        # read_verbs for the write side. `boot.agent_quickstart.write_verbs` derives
+        # from this so it advertises bare verb names the agent can call (no `--as`/
+        # `--stdin` CLI framing), finishing the de-CLI-ing of the agent surface
+        # (ADR 0056, ADR 0057).
+        def write_verbs
+          Textus::Action::VERBS
+            .select { |verb, klass| WRITE_VERBS.include?(verb) && mcp_surfaced?(klass) }
+            .keys.map(&:to_s)
+        end
+
+        def mcp_surfaced?(klass)
+          klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+        end
+
+        def call(name, session:, store:, args:) # rubocop:disable Metrics/AbcSize
+          klass = Textus::Action::VERBS[name.to_sym]
+          raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
+
+          spec = klass.contract
+          inputs = Textus::Contract::Binder.inputs_from_wire(spec, args)
+
+          invoke = lambda do |effective_inputs|
+            pos, kwargs = Textus::Contract::Binder.bind(spec, effective_inputs, session: session)
+            spec.args.select(&:positional).zip(pos).each { |a, v| kwargs[a.name] = v unless kwargs.key?(a.name) }
+            cmd_class = Textus::Gate::VERB_COMMAND.fetch(spec.verb) do
+              raise Textus::MCP::ToolError.new("unknown verb: #{spec.verb}")
+            end
+            merged = kwargs.merge(role: session.role)
+            filled = cmd_class.members.to_h { |m| [m, merged.key?(m) ? merged[m] : nil] }
+            cmd = cmd_class.new(**filled)
+            store.gate.dispatch(cmd)
+          end
+
+          result = if spec.around
+                     Textus::Contract::Around.with(spec.around, scope: store.as(session.role), inputs: inputs, session: session, &invoke)
+                   else
+                     invoke.call(inputs)
+                   end
+          Textus::Contract::View.render(spec, :default, result, inputs)
+        rescue Textus::Contract::MissingArgs => e
+          raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
+        rescue ContractDrift, CursorExpired
+          raise
+        rescue Textus::Error => e
+          raise ToolError.new("#{name}: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/mcp/errors.rb

@@ -0,0 +1,34 @@
+module Textus
+  module Surfaces
+    module MCP
+      # Manifest fingerprint changed mid-session. Client should re-boot.
+      class ContractDrift < Textus::Error
+        JSONRPC_CODE = -32_001
+
+        def initialize(message, details: {})
+          super("contract_drift", message, details: details)
+        end
+      end
+
+      # Audit cursor fell off the keep window. Client should re-boot and
+      # resume from the new latest_seq.
+      class CursorExpired < Textus::Error
+        JSONRPC_CODE = -32_002
+
+        def initialize(message, details: {})
+          super("cursor_expired", message, details: details)
+        end
+      end
+
+      # Tool execution failed (validation, authorization, IO). Wraps an
+      # underlying Textus::Error or generic StandardError.
+      class ToolError < Textus::Error
+        JSONRPC_CODE = -32_000
+
+        def initialize(message, details: {})
+          super("tool_error", message, details: details)
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/mcp/server.rb

@@ -0,0 +1,145 @@
+require "json"
+
+module Textus
+  module Surfaces
+    module MCP
+      # Stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. One line per
+      # message (NDJSON). Holds a single Session for the lifetime of stdin.
+      class Server
+        PROTOCOL_VERSION = "2024-11-05"
+        SERVER_INFO = { "name" => "textus", "version" => Textus::VERSION }.freeze
+        MAX_LINE_BYTES = 1_048_576 # 1 MB — protects against OOM from oversized tool calls
+
+        def initialize(store:, stdin: $stdin, stdout: $stdout, role: Textus::Role::DEFAULT)
+          @store   = store
+          @stdin   = stdin
+          @stdout  = stdout
+          @role    = role
+          @session = nil
+        end
+
+        def run
+          @stdin.each_line do |line|
+            line = line.strip
+            next if line.empty?
+
+            handle_line(line)
+          end
+        end
+
+        private
+
+        def handle_line(line)
+          if line.bytesize > MAX_LINE_BYTES
+            emit_error(nil, -32_700, "message too large (#{line.bytesize} bytes, limit #{MAX_LINE_BYTES})")
+            return
+          end
+          msg = JSON.parse(line)
+        rescue JSON::ParserError => e
+          emit_error(nil, -32_700, "parse error: #{e.message}")
+        else
+          dispatch(msg)
+        end
+
+        def dispatch(msg)
+          rid = msg["id"]
+          case msg["method"]
+          when "initialize"                then handle_initialize(rid, msg["params"] || {})
+          when "tools/list"                then handle_tools_list(rid)
+          when "tools/call"                then handle_tools_call(rid, msg["params"] || {})
+          when "ping"                      then emit_result(rid, {})
+          when "shutdown"                  then emit_result(rid, nil)
+          when "notifications/initialized" then nil
+          else emit_error(rid, -32_601, "method not found: #{msg["method"]}")
+          end
+        end
+
+        def handle_initialize(rid, _params)
+          # The acting role IS the resolved connection role (ADR 0040): the MCP
+          # transport defaults to `agent`, which can write the queue, so its
+          # propose_lane resolves directly. If a connection's role cannot propose,
+          # propose_lane is nil and the `propose` tool reports that honestly.
+          propose_lane = @store.manifest.policy.propose_lane_for(@role)
+
+          @session = Session.new(
+            role: @role,
+            cursor: @store.audit_log.latest_seq,
+            propose_lane: propose_lane,
+            contract_etag: contract_etag,
+          )
+
+          # ADR 0075: announce the connection to connect-time hooks with the
+          # resolved role. Distinct from :store_loaded (fired at Store.new under
+          # the default role, before any connection's role is known).
+          @store.steps.publish(
+            :session_opened,
+            ctx: Step::Context.new(scope: @store.as(@role)),
+            role: @role,
+            cursor: @session.cursor,
+          )
+
+          emit_result(rid, {
+                        "protocolVersion" => PROTOCOL_VERSION,
+                        "serverInfo" => SERVER_INFO,
+                        "capabilities" => { "tools" => {} },
+                      })
+        end
+
+        def handle_tools_list(rid)
+          emit_result(rid, { "tools" => Catalog.tool_schemas })
+        end
+
+        def handle_tools_call(rid, params)
+          unless @session
+            emit_error(rid, -32_002, "session not initialized; call 'initialize' first")
+            return
+          end
+
+          name = params["name"]
+          args = params["arguments"] || {}
+
+          # ADR 0083: the contract-drift guard gates mutating verbs — every MCP
+          # verb that is NOT a pure read (Write:: + the destructive Maintenance::
+          # verbs drain/data_mv/key_*_prefix). Reads and boot bypass it (a stale
+          # read returns on-disk truth; boot re-orients). Keying on read_verbs
+          # (not write_verbs) keeps the destructive Maintenance:: verbs gated.
+          @session.check_etag!(contract_etag) unless Catalog.read_verbs.include?(name)
+
+          result = Catalog.call(name, session: @session, store: @store, args: args)
+          @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "pulse"
+          @session = @session.with(contract_etag: contract_etag) if name == "boot"
+
+          emit_result(rid, {
+                        "content" => [{ "type" => "text", "text" => JSON.dump(result) }],
+                        "isError" => false,
+                      })
+        rescue ContractDrift => e
+          emit_error(rid, ContractDrift::JSONRPC_CODE, e.message)
+        rescue CursorExpired => e
+          emit_error(rid, CursorExpired::JSONRPC_CODE, e.message)
+        rescue ToolError => e
+          emit_error(rid, ToolError::JSONRPC_CODE, e.message)
+        rescue StandardError => e
+          emit_error(rid, -32_603, "internal: #{e.class}: #{e.message}")
+        end
+
+        def contract_etag
+          Textus::Etag.for_contract(@store.root)
+        end
+
+        def emit_result(rid, result)
+          write({ "jsonrpc" => "2.0", "id" => rid, "result" => result })
+        end
+
+        def emit_error(rid, code, message)
+          write({ "jsonrpc" => "2.0", "id" => rid, "error" => { "code" => code, "message" => message } })
+        end
+
+        def write(obj)
+          @stdout.puts(JSON.dump(obj))
+          @stdout.flush
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/mcp/session.rb

@@ -0,0 +1,9 @@
+module Textus
+  module Surfaces
+    module MCP
+      # The session value now lives in core (ADR 0036); retained here as an
+      # alias so existing MCP references keep resolving.
+      Session = Textus::Session
+    end
+  end
+end

data/lib/textus/surfaces/mcp/tool_schemas.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Surfaces
+    module MCP
+      # Kept for name stability (ADR 0039). The JSON schemas are DERIVED from
+      # per-verb contracts; this delegates to MCP::Catalog. The hand-written
+      # array is gone — a kwarg rename now updates the schema automatically (and
+      # the signature guard fails if the contract lags the use-case).
+      module ToolSchemas
+        module_function
+
+        def all
+          Catalog.tool_schemas
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/mcp.rb

@@ -0,0 +1,8 @@
+module Textus
+  module Surfaces
+    # The agent gate. Stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05.
+    # Wraps Textus::Surfaces::RoleScope as auto-derived tools. See ADR 0015.
+    module MCP
+    end
+  end
+end

data/lib/textus/surfaces/role_scope.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Textus
+  module Surfaces
+    # Role-scoped identity carrier. Holds the acting identity (role,
+    # correlation_id, dry_run) bound to a container. All verb methods
+    # (put, get, accept, ...) are injected by textus.rb's define_method
+    # loop, which dispatches directly through Gate.
+    class RoleScope
+      attr_reader :container, :role, :correlation_id
+
+      def initialize(container:, role:, dry_run: false, correlation_id: nil)
+        @container      = container
+        @role           = role.to_s
+        @dry_run        = dry_run
+        @correlation_id = correlation_id || SecureRandom.uuid
+      end
+
+      def dry_run? = !!@dry_run
+
+      def with_role(role)
+        self.class.new(container: @container, role:, dry_run: @dry_run, correlation_id: @correlation_id)
+      end
+
+      def with_correlation_id(cid)
+        self.class.new(container: @container, role: @role, dry_run: @dry_run, correlation_id: cid)
+      end
+
+      def with_dry_run
+        self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
+      end
+
+      def hook_context
+        @hook_context ||= Textus::Step::Context.new(scope: self)
+      end
+    end
+  end
+end

data/lib/textus/surfaces/watcher.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Textus
+  module Surfaces
+    class Watcher
+      def initialize(container:)
+        @container = container
+        @queue = Textus::Ports::Queue.new(root: container.root)
+      end
+
+      def tick
+        Textus::Background::Planner::Plan.seed(
+          container: @container,
+          queue: @queue,
+          role: Textus::Role::AUTOMATION,
+        )
+        @queue.reclaim(now: Textus::Ports::Clock.new.now)
+        Textus::Background::Worker.for(container: @container, queue: @queue).drain
+      end
+
+      def run(poll: nil)
+        interval = poll || @container.manifest.data.worker_config[:poll]
+        lock = Textus::Ports::WatcherLock.new(@container.root)
+        lock.acquire
+        begin
+          loop do
+            tick
+            sleep(interval)
+          end
+        ensure
+          lock.release
+        end
+      end
+    end
+  end
+end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.52.0"
+  VERSION = "0.53.0"
   PROTOCOL = "textus/3"
 end