textus 0.22.0 → 0.26.0

data/lib/textus/manifest/policy.rb

@@ -0,0 +1,48 @@
+module Textus
+  class Manifest
+    # Authority over zones and roles derived from a Manifest::Data snapshot.
+    # Encapsulates the lookups previously living on Manifest itself
+    # (zone_writers, zone_kinds, permission_for, role_kind, roles_with_kind).
+    class Policy
+      def initialize(data)
+        @data = data
+        @zone_kinds_cache = {}
+      end
+
+      def zone_writers(zone_name)
+        @data.zones[zone_name] or raise UsageError.new("undeclared zone '#{zone_name}'")
+      end
+
+      def zone_readers
+        @data.zone_readers
+      end
+
+      def permission_for(zone_name)
+        Textus::Domain::Permission.new(
+          zone: zone_name,
+          write_policy: zone_writers(zone_name),
+          read_policy: @data.zone_readers[zone_name] || :all,
+        )
+      end
+
+      def zone_kinds(zone_name)
+        @zone_kinds_cache[zone_name] ||= zone_writers(zone_name).each_with_object(Set.new) do |w, acc|
+          k = role_kind(w)
+          acc << k if k
+        end.freeze
+      end
+
+      def role_mapping
+        @data.role_mapping
+      end
+
+      def role_kind(name)
+        @data.role_mapping[name]
+      end
+
+      def roles_with_kind(kind)
+        @data.role_mapping.each_with_object([]) { |(name, k), acc| acc << name if k == kind }
+      end
+    end
+  end
+end

data/lib/textus/manifest/resolver.rb

@@ -1,19 +1,19 @@
 module Textus
   class Manifest
     class Resolver
-      Resolution = Data.define(:entry, :path, :remaining)
+      Resolution = ::Data.define(:entry, :path, :remaining)
 
-      def initialize(manifest)
-        @manifest = manifest
+      def initialize(data)
+        @data = data
       end
 
       def resolve(key)
-        @manifest.validate_key!(key)
+        @data.validate_key!(key)
         segments = key.split(".")
-        candidates = @manifest.entries
-                              .map { |e| [e, e.key.split(".")] }
-                              .select { |(_, esegs)| esegs == segments[0, esegs.length] }
-                              .sort_by { |(_, esegs)| -esegs.length }
+        candidates = @data.entries
+                          .map { |e| [e, e.key.split(".")] }
+                          .select { |(_, esegs)| esegs == segments[0, esegs.length] }
+                          .sort_by { |(_, esegs)| -esegs.length }
         raise UnknownKey.new(key, suggestions: suggestions_for(key)) if candidates.empty?
 
         entry, esegs = candidates.first
@@ -23,7 +23,7 @@ module Textus
 
       def suggestions_for(key)
         candidates = enumerate.map { |r| r[:key] }
-        candidates.concat(@manifest.entries.reject { |e| nested_entry?(e) }.map(&:key))
+        candidates.concat(@data.entries.reject { |e| nested_entry?(e) }.map(&:key))
         candidates.uniq!
         Key::Distance.suggest(key, candidates, limit: 5)
       rescue StandardError
@@ -31,7 +31,7 @@ module Textus
       end
 
       def enumerate(prefix: nil)
-        out = @manifest.entries.flat_map { |entry| nested_entry?(entry) ? enumerate_nested(entry) : enumerate_leaf(entry) }
+        out = @data.entries.flat_map { |entry| nested_entry?(entry) ? enumerate_nested(entry) : enumerate_leaf(entry) }
         out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
         out.sort_by { |row| row[:key] }
       end
@@ -53,10 +53,10 @@ module Textus
 
           index_fn = entry.index_filename
           path = if index_fn
-                   File.join(@manifest.root, "zones", entry.path, *remaining, index_fn)
+                   File.join(@data.root, "zones", entry.path, *remaining, index_fn)
                  else
                    primary_ext = Textus::Entry.for_format(entry.format).extensions.first
-                   File.join(@manifest.root, "zones", entry.path, *remaining) + primary_ext
+                   File.join(@data.root, "zones", entry.path, *remaining) + primary_ext
                  end
           Resolution.new(entry: entry, path: path, remaining: remaining)
         end
@@ -68,7 +68,7 @@ module Textus
       end
 
       def enumerate_nested(entry)
-        base = File.join(@manifest.root, "zones", entry.path)
+        base = File.join(@data.root, "zones", entry.path)
         return [] unless File.directory?(base)
 
         entry_index_filename = entry.index_filename
@@ -101,7 +101,7 @@ module Textus
       end
 
       def resolve_leaf_path(entry)
-        Textus::Key::Path.resolve(@manifest, entry)
+        Textus::Key::Path.resolve(@data, entry)
       end
 
       def nested_glob(format)

data/lib/textus/manifest/rules.rb

@@ -1,7 +1,7 @@
 module Textus
   class Manifest
     class Rules
-      RuleSet = Data.define(:refresh, :handler_allowlist, :promote, :retention)
+      RuleSet = ::Data.define(:refresh, :handler_allowlist, :promote, :retention)
       EMPTY_SET = RuleSet.new(refresh: nil, handler_allowlist: nil, promote: nil, retention: nil)
 
       def self.parse(raw)

data/lib/textus/manifest.rb

@@ -1,127 +1,69 @@
 require "yaml"
+
+module Textus
+  # Manifest is the composition record for a parsed manifest. It bundles
+  # four collaborators:
+  #
+  #   * data     — frozen value: raw, root, zones, entries, audit_config, role_mapping
+  #   * resolver — resolves keys → entry + path
+  #   * policy   — zone/role authority (zone_writers, zone_kinds, permission_for, …)
+  #   * rules    — match-block rule engine (refresh, handler allowlist, promotion, …)
+  #
+  # Use `manifest.data.entries`, `manifest.policy.zone_kinds(z)`, etc.
+  Manifest = Data.define(:data, :resolver, :policy, :rules)
+end
+
 require_relative "manifest/schema"
+require_relative "manifest/data"
+require_relative "manifest/policy"
 require_relative "manifest/resolver"
 require_relative "manifest/role_kinds"
 
-module Textus
+# Reopen Textus::Manifest (defined above as a Data.define) to attach
+# class-level loaders and helpers.
+module Textus # rubocop:disable Style/OneClassPerFile
   class Manifest
-    attr_reader :root, :entries, :raw
-
-    def zones
-      @zones ||= Array(@raw["zones"]).to_h { |z| [z["name"], Array(z["write_policy"])] }
-    end
-
-    def zone_readers
-      @zone_readers ||= Array(@raw["zones"]).to_h do |z|
-        rp = z["read_policy"]
-        [z["name"], rp.nil? ? :all : Array(rp)]
+    class << self
+      def parse(yaml_text, root: ".")
+        raw = YAML.safe_load(yaml_text, aliases: false)
+        check_version!(raw, "<string>")
+        build(raw, root)
       end
-    end
-
-    def zone_writers(zone_name)
-      zones[zone_name] or raise UsageError.new("undeclared zone '#{zone_name}'")
-    end
-
-    def permission_for(zone_name)
-      Textus::Domain::Permission.new(
-        zone: zone_name,
-        write_policy: zone_writers(zone_name),
-        read_policy: zone_readers[zone_name] || :all,
-      )
-    end
-
-    AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
-
-    def audit_config
-      raw = @raw["audit"] || {}
-      {
-        max_size: raw["max_size"] || AUDIT_DEFAULTS[:max_size],
-        keep: raw["keep"] || AUDIT_DEFAULTS[:keep],
-      }
-    end
-
-    def role_mapping
-      @role_mapping ||= RoleKinds.resolve(@raw["roles"])
-    end
-
-    def role_kind(name)
-      role_mapping[name]
-    end
-
-    def roles_with_kind(kind)
-      role_mapping.each_with_object([]) { |(name, k), acc| acc << name if k == kind }
-    end
 
-    def zone_kinds(zone_name)
-      @zone_kinds_cache ||= {}
-      @zone_kinds_cache[zone_name] ||= zone_writers(zone_name).each_with_object(Set.new) do |w, acc|
-        k = role_kind(w)
-        acc << k if k
-      end.freeze
-    end
-
-    def self.parse(yaml_text, root: ".")
-      raw = YAML.safe_load(yaml_text, aliases: false)
-      check_version!(raw, "<string>")
-      new(root, raw)
-    end
-
-    def self.load(root)
-      manifest_path = File.join(root, "manifest.yaml")
-      raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
-
-      raw = YAML.safe_load_file(manifest_path, aliases: false)
-      check_version!(raw, manifest_path)
-      new(root, raw)
-    end
-
-    def self.check_version!(raw, source)
-      return if raw["version"] == PROTOCOL
-
-      raise BadFrontmatter.new(
-        source,
-        "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
-      )
-    end
-    private_class_method :check_version!
-
-    def initialize(root, raw)
-      @root = root
-      @raw = raw
-      raise BadFrontmatter.new(File.join(root, "manifest.yaml"), "manifest must declare zones:") if Array(raw["zones"]).empty?
-
-      Schema.validate!(raw)
+      def load(root)
+        manifest_path = File.join(root, "manifest.yaml")
+        raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
 
-      @entries = Array(raw["entries"]).map do |e|
-        entry = Manifest::Entry::Parser.call(self, e)
-        Manifest::Entry::Validators.run_all(entry)
-        entry
+        raw = YAML.safe_load_file(manifest_path, aliases: false)
+        check_version!(raw, manifest_path)
+        build(raw, root)
       end
-      validate_declared_keys!
-    end
-
-    def rules
-      @rules ||= Textus::Manifest::Rules.parse(@raw["rules"] || [])
-    end
 
-    def rules_for(key)
-      rules.for(key)
-    end
-
-    def resolver
-      @resolver ||= Resolver.new(self)
-    end
-
-    def validate_key!(key)
-      raise UsageError.new("empty key") if key.nil? || key.empty?
-
-      Key::Grammar.validate!(key)
-    end
+      private
+
+      def build(raw, root)
+        data = Manifest::Data.parse(raw, root: root)
+        composition = new(
+          data: data,
+          resolver: Manifest::Resolver.new(data),
+          policy: data.policy,
+          rules: Manifest::Rules.parse(raw["rules"] || []),
+        )
+        # Re-point entries' back-reference from Data to the composition
+        # record. Entries call `@manifest.policy.*` / `@manifest.resolver.*`
+        # at use time (see Entry::Base, Entry::Nested).
+        data.entries.each { |e| e.instance_variable_set(:@manifest, composition) }
+        composition
+      end
 
-    private
+      def check_version!(raw, source)
+        return if raw["version"] == PROTOCOL
 
-    def validate_declared_keys!
-      @entries.each { |e| validate_key!(e.key) }
+        raise BadFrontmatter.new(
+          source,
+          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
+        )
+      end
     end
   end
 end

data/lib/textus/mcp/errors.rb

@@ -0,0 +1,32 @@
+module Textus
+  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

data/lib/textus/mcp/server.rb

@@ -0,0 +1,127 @@
+require "json"
+require "digest"
+
+module Textus
+  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
+
+      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)
+        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)
+        proposer = @store.manifest.policy.roles_with_kind(:proposer).first
+        propose_zone = nil
+        if proposer
+          @store.manifest.data.zones.each do |zname, writers|
+            if writers.include?(proposer) && zname.include?("review")
+              propose_zone = zname
+              break
+            end
+          end
+        end
+
+        @session = Session.new(
+          role: @role,
+          cursor: @store.audit_log.latest_seq,
+          propose_zone: propose_zone,
+          manifest_etag: manifest_etag,
+        )
+
+        emit_result(rid, {
+                      "protocolVersion" => PROTOCOL_VERSION,
+                      "serverInfo" => SERVER_INFO,
+                      "capabilities" => { "tools" => {} },
+                    })
+      end
+
+      def handle_tools_list(rid)
+        emit_result(rid, { "tools" => ToolSchemas.all })
+      end
+
+      def handle_tools_call(rid, params)
+        unless @session
+          emit_error(rid, -32_002, "session not initialized; call 'initialize' first")
+          return
+        end
+
+        @session.check_etag!(manifest_etag)
+
+        name = params["name"]
+        args = params["arguments"] || {}
+        result = Tools.call(name, session: @session, store: @store, args: args)
+        @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "tick"
+
+        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 manifest_etag
+        Digest::SHA256.hexdigest(File.read(File.join(@store.root, "manifest.yaml")))
+      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

data/lib/textus/mcp/session.rb

@@ -0,0 +1,31 @@
+module Textus
+  module MCP
+    # Per-connection state held by the server. Immutable; advance_cursor
+    # returns a new instance.
+    class Session
+      attr_reader :role, :cursor, :propose_zone, :manifest_etag
+
+      def initialize(role:, cursor:, propose_zone:, manifest_etag:)
+        @role = role
+        @cursor = cursor
+        @propose_zone = propose_zone
+        @manifest_etag = manifest_etag
+      end
+
+      def advance_cursor(new_cursor)
+        self.class.new(
+          role: @role, cursor: new_cursor,
+          propose_zone: @propose_zone, manifest_etag: @manifest_etag
+        )
+      end
+
+      def check_etag!(observed_etag)
+        return if observed_etag == @manifest_etag
+
+        raise ContractDrift.new(
+          "manifest changed (was #{@manifest_etag[0, 8]}, now #{observed_etag[0, 8]}); re-run boot",
+        )
+      end
+    end
+  end
+end

data/lib/textus/mcp/tool_schemas.rb

@@ -0,0 +1,71 @@
+module Textus
+  module MCP
+    # JSON-Schema definitions for every MCP tool's inputSchema. Returned by
+    # the server in tools/list. Static today — a follow-up will enrich with
+    # manifest-derived enums for `zone`, `key`, etc.
+    module ToolSchemas
+      module_function
+
+      def all # rubocop:disable Metrics/MethodLength
+        [
+          tool("boot", "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart.", {}, []),
+          tool("tick", "Delta since cursor. Returns {cursor, changed, stale, pending_review, doctor}.",
+               { "since" => { "type" => "integer", "minimum" => 0 } }, []),
+          tool("find", "List keys filtered by zone and/or prefix.",
+               { "zone" => { "type" => "string" }, "prefix" => { "type" => "string" } }, []),
+          tool("read", "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness).",
+               { "key" => { "type" => "string" } }, ["key"]),
+          tool("write", "Create or update an entry. Schema-validated. Returns {uid, etag}.",
+               {
+                 "key" => { "type" => "string" },
+                 "meta" => { "type" => "object" },
+                 "body" => { "type" => "string" },
+                 "content" => { "type" => "object" },
+                 "if_etag" => { "type" => "string" },
+               }, %w[key meta]),
+          tool("propose", "Write a proposal to the session's propose_zone. Auto-prefixes the key.",
+               {
+                 "key" => { "type" => "string", "description" => "Key relative to propose_zone, e.g. 'proposal.feature-x'" },
+                 "meta" => { "type" => "object" },
+                 "body" => { "type" => "string" },
+               }, %w[key meta]),
+          tool("refresh", "Run an intake refresh for one key. Returns the refresh Outcome.",
+               { "key" => { "type" => "string" } }, ["key"]),
+          tool("refresh_stale", "Refresh all stale intake entries, optionally scoped by zone/prefix.",
+               {
+                 "zone" => { "type" => "string" },
+                 "prefix" => { "type" => "string" },
+               }, []),
+          tool("schema", "Return the schema (field shape) for an entry family.",
+               { "family" => { "type" => "string" } }, ["family"]),
+          tool("rules", "Return effective rules for a key (refresh, promote, ...).",
+               { "key" => { "type" => "string" } }, ["key"]),
+          tool("key_mv_prefix",
+               "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false.",
+               { "from_prefix" => { "type" => "string" }, "to_prefix" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
+               %w[from_prefix to_prefix]),
+          tool("key_delete_prefix", "Bulk-delete every leaf key under prefix.",
+               { "prefix" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
+               ["prefix"]),
+          tool("zone_mv", "Rename a zone — manifest + files. Refuses if destination exists.",
+               { "from" => { "type" => "string" }, "to" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
+               %w[from to]),
+          tool("rule_lint", "Diff candidate manifest YAML's rules against the live manifest. No writes.",
+               { "candidate_yaml" => { "type" => "string" } },
+               ["candidate_yaml"]),
+          tool("migrate", "Run a YAML migration plan (multi-op).",
+               { "plan_yaml" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
+               ["plan_yaml"]),
+        ].freeze
+      end
+
+      def tool(name, description, properties, required)
+        {
+          name: name,
+          description: description,
+          inputSchema: { type: "object", properties: properties, required: required },
+        }
+      end
+    end
+  end
+end