textus 0.52.0 → 0.54.0

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 Textus::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,25 @@
+module Textus
+  module Surfaces
+    module MCP
+      # 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/routing.rb

@@ -0,0 +1,51 @@
+module Textus
+  module Surfaces
+    module MCP
+      # Protocol routing for the MCP JSON-RPC server. Mixed into Server so all
+      # handle_* and emit_* methods are in scope without exposing them publicly.
+      module Routing
+        TOOL_METHODS     = %w[initialize tools/list tools/call].freeze
+        RESOURCE_METHODS = %w[resources/list resources/read].freeze
+
+        def dispatch(msg)
+          rid    = msg["id"]
+          params = msg["params"] || {}
+          route(msg["method"], rid, params)
+        end
+
+        private
+
+        def route(method, rid, params)
+          return route_tool(method, rid, params)     if TOOL_METHODS.include?(method)
+          return route_resource(method, rid, params) if RESOURCE_METHODS.include?(method)
+
+          route_protocol(method, rid)
+        end
+
+        def route_tool(method, rid, params)
+          case method
+          when "initialize" then handle_initialize(rid, params)
+          when "tools/list" then handle_tools_list(rid)
+          when "tools/call" then handle_tools_call(rid, params)
+          end
+        end
+
+        def route_resource(method, rid, params)
+          case method
+          when "resources/list" then handle_resources_list(rid)
+          when "resources/read" then handle_resources_read(rid, params)
+          end
+        end
+
+        def route_protocol(method, rid)
+          case method
+          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: #{method}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,184 @@
+require "json"
+require_relative "routing"
+
+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
+        include Routing
+
+        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)
+          return reject_oversized(line) if line.bytesize > MAX_LINE_BYTES
+
+          parse_and_dispatch(line)
+        end
+
+        def reject_oversized(line)
+          emit_error(nil, -32_700, "message too large (#{line.bytesize} bytes, limit #{MAX_LINE_BYTES})")
+        end
+
+        def parse_and_dispatch(line)
+          dispatch(JSON.parse(line))
+        rescue JSON::ParserError => e
+          emit_error(nil, -32_700, "parse error: #{e.message}")
+        end
+
+        def handle_initialize(rid, _params)
+          @session = build_session
+          emit_result(rid, {
+                        "protocolVersion" => PROTOCOL_VERSION,
+                        "serverInfo" => SERVER_INFO,
+                        "capabilities" => { "tools" => {}, "resources" => {} },
+                      })
+        end
+
+        def build_session
+          # 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.
+          Session.new(
+            role: @role,
+            cursor: @store.audit_log.latest_seq,
+            propose_lane: @store.manifest.policy.propose_lane_for(@role),
+            contract_etag: contract_etag,
+          )
+        end
+
+        def handle_tools_list(rid)
+          emit_result(rid, { "tools" => Catalog.tool_schemas })
+        end
+
+        def handle_tools_call(rid, params)
+          return unless session_ready?(rid)
+
+          invoke_tool(rid, params["name"], params["arguments"] || {})
+        rescue Textus::ContractDrift, CursorExpired, ToolError => e
+          emit_error(rid, e.class::JSONRPC_CODE, e.message)
+        rescue StandardError => e
+          emit_error(rid, -32_603, "internal: #{e.class}: #{e.message}")
+        end
+
+        def session_ready?(rid)
+          return true if @session
+
+          emit_error(rid, -32_002, "session not initialized; call 'initialize' first")
+          false
+        end
+
+        def invoke_tool(rid, name, args)
+          # ADR 0083: contract-drift guard gates mutating verbs only
+          @session.check_etag!(contract_etag) unless Catalog.read_verbs.include?(name)
+          result = Catalog.call(name, session: @session, store: @store, args: args)
+          update_session_for(name)
+          emit_tool_result(rid, result)
+        end
+
+        def update_session_for(name)
+          @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "pulse"
+          @session = @session.with(contract_etag: contract_etag) if name == "boot"
+        end
+
+        def emit_tool_result(rid, result)
+          emit_result(rid, {
+                        "content" => [{ "type" => "text", "text" => JSON.dump(result) }],
+                        "isError" => false,
+                      })
+        end
+
+        def handle_resources_list(rid)
+          emit_result(rid, { "resources" => machine_resources })
+        end
+
+        def machine_resources
+          machine_lane = @store.manifest.policy.machine_lane
+          return [] unless machine_lane
+
+          produced_entries(machine_lane).map { |e| resource_descriptor(e) }
+        end
+
+        def produced_entries(machine_lane)
+          @store.manifest.data.entries
+                .select { |e| e.lane == machine_lane && e.is_a?(Textus::Manifest::Entry::Produced) }
+        end
+
+        def resource_descriptor(entry)
+          {
+            "uri" => "textus://#{entry.key.tr(".", "/")}",
+            "name" => entry.key,
+            "mimeType" => mime_for_format(entry.format),
+          }
+        end
+
+        def handle_resources_read(rid, params)
+          uri = params["uri"].to_s
+          key = uri.delete_prefix("textus://").tr("/", ".")
+          emit_result(rid, resource_contents(uri, key))
+        rescue Textus::Error => e
+          emit_error(rid, ToolError::JSONRPC_CODE, "resource read failed: #{e.message}")
+        end
+
+        def resource_contents(uri, key)
+          env  = @store.as(@role).get(key)
+          text = resource_text(env.content || env.body || "")
+          mime = mime_for_format(@store.manifest.resolver.resolve(key).entry.format)
+          { "contents" => [{ "uri" => uri, "mimeType" => mime, "text" => text }] }
+        end
+
+        def resource_text(content)
+          content.is_a?(Hash) ? JSON.dump(content) : content.to_s
+        end
+
+        def contract_etag
+          Textus::Etag.for_contract(@store.root)
+        end
+
+        def mime_for_format(format)
+          case format.to_s
+          when "json" then "application/json"
+          when "yaml" then "application/yaml"
+          else             "text/plain"
+          end
+        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,34 @@
+# 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
+    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::JobStore.new(root: container.root)
+      end
+
+      def tick
+        Textus::Jobs::Planner.seed(
+          container: @container,
+          queue: @queue,
+          role: Textus::Role::AUTOMATION,
+        )
+        @queue.reclaim(now: Textus::Ports::Clock.new.now)
+        Textus::Jobs::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.54.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/workflow/collector.rb

@@ -0,0 +1,27 @@
+module Textus
+  module Workflow
+    class Collector
+      @current = nil
+
+      class << self
+        attr_reader :current
+      end
+
+      def self.with(collector)
+        prev      = @current
+        @current  = collector
+        yield
+      ensure
+        @current = prev
+      end
+
+      def initialize(registry)
+        @registry = registry
+      end
+
+      def register(defn)
+        @registry.register(defn)
+      end
+    end
+  end
+end

data/lib/textus/workflow/context.rb

@@ -0,0 +1,5 @@
+module Textus
+  module Workflow
+    Context = Data.define(:key, :entry, :config, :lane, :container, :call)
+  end
+end