textus 0.52.0 → 0.54.0

data/lib/textus/cli/verb.rb

@@ -1,116 +0,0 @@
-require "json"
-require "optparse"
-
-module Textus
-  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
-
-      # Returns a Call value bound to the resolved role. Convenience for
-      # verbs whose only pre-call boilerplate is resolving the role and
-      # wrapping it in a Call.
-      def context_for(store)
-        Textus::Call.build(role: resolved_role(store))
-      end
-
-      # Returns a RoleScope bound to the resolved role.
-      def session_for(store)
-        store.as(resolved_role(store))
-      end
-
-      # The input stream — the source for a `cli_stdin` envelope (ADR 0068).
-      attr_reader :stdin
-    end
-  end
-end

data/lib/textus/cli.rb

@@ -1,138 +0,0 @@
-require "json"
-require "optparse"
-
-module Textus
-  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] [--zone=Z]
-          textus where KEY
-          textus get KEY
-          textus put KEY --stdin --as=ROLE
-          textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
-          textus blame KEY [--limit=N]
-          textus doctor
-          textus boot
-
-          textus key {delete,mv,uid}
-          textus rule {explain,lint,list}
-          textus schema {diff,init,migrate,show}
-          textus hook {list,run}
-      HELP
-    end
-  end
-end

data/lib/textus/dispatcher.rb

@@ -1,54 +0,0 @@
-module Textus
-  # Static verb → use-case map. Canonical lookup as of 0.27.0; replaces the
-  # Application::UseCase registry whose entries were populated by file-load
-  # side effects in 0.26.x.
-  module Dispatcher
-    VERBS = {
-      # Write
-      put: Textus::Write::Put,
-      propose: Textus::Write::Propose,
-      key_delete: Textus::Write::KeyDelete,
-      key_mv: Textus::Write::KeyMv,
-      accept: Textus::Write::Accept,
-      reject: Textus::Write::Reject,
-      enqueue: Textus::Write::Enqueue,
-      # Read
-      get: Textus::Read::Get,
-      list: Textus::Read::List,
-      where: Textus::Read::Where,
-      uid: Textus::Read::Uid,
-      blame: Textus::Read::Blame,
-      audit: Textus::Read::Audit,
-      freshness: Textus::Read::Freshness,
-      deps: Textus::Read::Deps,
-      rdeps: Textus::Read::Rdeps,
-      pulse: Textus::Read::Pulse,
-      rule_explain: Textus::Read::RuleExplain,
-      rule_list: Textus::Read::RuleList,
-      published: Textus::Read::Published,
-      schema_show: Textus::Read::SchemaEnvelope,
-      validate_all: Textus::Read::ValidateAll,
-      doctor: Textus::Read::Doctor,
-      boot: Textus::Read::Boot,
-      capabilities: Textus::Read::Capabilities,
-      jobs: Textus::Read::Jobs,
-
-      # Maintenance
-      zone_mv: Textus::Maintenance::ZoneMv,
-      key_mv_prefix: Textus::Maintenance::KeyMvPrefix,
-      key_delete_prefix: Textus::Maintenance::KeyDeletePrefix,
-      drain: Textus::Maintenance::Drain,
-      rule_lint: Textus::Maintenance::RuleLint,
-    }.freeze
-
-    def self.fetch(verb)
-      VERBS.fetch(verb.to_sym) { raise UsageError.new("unknown verb: #{verb.inspect}") }
-    end
-
-    # Single home for the uniform use-case invocation protocol (ADR 0023):
-    # look up the verb, construct on (container:, call:), and invoke #call.
-    def self.invoke(verb, container:, call:, args: [], kwargs: {})
-      fetch(verb).new(container: container, call: call).call(*args, **kwargs)
-    end
-  end
-end

data/lib/textus/doctor/check/handler_allowlist.rb

@@ -1,34 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # For every entry with an `intake.handler`, look up its handler_allowlist
-      # policy (if any) and verify the declared handler is allowed. Emits a
-      # failure when the handler is rejected by policy.
-      class HandlerAllowlist < Check
-        def call
-          out = []
-          manifest.data.entries.each do |mentry|
-            next unless mentry.intake?
-
-            handler = mentry.handler
-
-            allow = manifest.rules.for(mentry.key).handler_allowlist
-            next if allow.nil?
-            next if allow.allows?(handler)
-
-            out << {
-              "code" => "policy.handler_not_allowed",
-              "level" => "error",
-              "subject" => mentry.key,
-              "message" => "entry '#{mentry.key}' declares intake.handler='#{handler}' but the " \
-                           "handler_allowlist policy permits only: #{allow.handlers.join(", ")}",
-              "fix" => "either change intake.handler to one of [#{allow.handlers.join(", ")}], " \
-                       "or extend the handler_allowlist policy in .textus/manifest.yaml",
-            }
-          end
-          out
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/hooks.rb

@@ -1,32 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class Hooks < Check
-        def call
-          out = []
-          dir = File.join(root, "hooks")
-          return out unless File.directory?(dir)
-
-          Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
-            events = Textus::Hooks::EventBus.new
-            rpc    = Textus::Hooks::RpcRegistry.new
-            Textus.drain_hook_blocks
-            begin
-              load(f)
-              Textus.drain_hook_blocks.each { |b| b.call(Textus::Hooks::Loader::Dsl.new(events: events, rpc: rpc)) }
-            end
-          rescue StandardError, ScriptError => e
-            out << {
-              "code" => "hook.load_failed",
-              "level" => "error",
-              "subject" => File.basename(f),
-              "message" => "#{e.class}: #{e.message}",
-              "fix" => "open #{f} and fix the syntax/load error",
-            }
-          end
-          out
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/intake_registration.rb

@@ -1,46 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class IntakeRegistration < Check
-        BUILTIN = %i[json csv markdown-links ical-events rss].freeze
-
-        def call
-          declared = collect_declared_handlers
-          registered = rpc.names(:resolve_handler).to_set
-
-          out = (declared - registered).map do |name|
-            {
-              "code" => "intake.handler_missing",
-              "level" => "error",
-              "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no resolve_handler hook for '#{name}' is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.hook { |reg| reg.on(:resolve_handler, :#{name}) { ... } }`",
-            }
-          end
-
-          (registered - declared - BUILTIN.to_set).each do |name|
-            out << {
-              "code" => "intake.handler_orphan",
-              "level" => "warning",
-              "subject" => name.to_s,
-              "message" => "resolve_handler hook '#{name}' is registered but no manifest entry references it",
-              "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
-            }
-          end
-
-          out
-        end
-
-        private
-
-        def collect_declared_handlers
-          set = Set.new
-          manifest.data.entries.each do |mentry|
-            set << mentry.handler.to_sym if mentry.intake?
-          end
-          set
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/action.rb

@@ -1,9 +0,0 @@
-module Textus
-  module Domain
-    module Action
-      Return = Data.define
-      FetchSync  = Data.define
-      FetchTimed = Data.define(:budget_ms)
-    end
-  end
-end

data/lib/textus/domain/jobs/registry.rb

@@ -1,37 +0,0 @@
-module Textus
-  module Domain
-    module Jobs
-      # Closed allow-list of runnable job types. The general `enqueue` surface
-      # (a later phase) can only push types registered here — that is the safety
-      # boundary that stops the "general runner" from running arbitrary code.
-      class Registry
-        Entry = Struct.new(:handler, :max_attempts, :required_role, keyword_init: true)
-
-        def initialize
-          @entries = {}
-        end
-
-        # required_role: a role the caller must hold to enqueue this type via the
-        # general `enqueue` surface (nil = any caller). The closed allow-list is
-        # the primary safety boundary; this is defence-in-depth for destructive
-        # types.
-        def register(type, handler:, max_attempts: 3, required_role: nil)
-          @entries[type.to_s] = Entry.new(handler: handler, max_attempts: max_attempts, required_role: required_role)
-        end
-
-        def registered?(type)
-          @entries.key?(type.to_s)
-        end
-
-        def lookup(type)
-          @entries.fetch(type.to_s) do
-            raise Textus::UsageError.new(
-              "unregistered job type '#{type}'",
-              hint: "register the type in Domain::Jobs::Registry before enqueueing it",
-            )
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/permission.rb

@@ -1,7 +0,0 @@
-module Textus
-  module Domain
-    Permission = Data.define(:zone, :writers) do
-      def allows_write?(role) = writers.include?(role.to_s)
-    end
-  end
-end

data/lib/textus/domain/policy/base_guards.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # The CLOSED floor (ADR 0031 §4): predicate names every transition
-      # evaluates regardless of rules:. rules[].guard only ADDS to these.
-      module BaseGuards
-        # The minimal floor — only what the verb is meaningless without.
-        # schema_valid / etag_match / fresh_within are NOT here: they are
-        # composable-only, added per-key via rules[].guard (ADR 0031).
-        BASE = {
-          put: %w[zone_writable_by],
-          key_delete: %w[zone_writable_by],
-          key_mv: %w[zone_writable_by],
-          accept: %w[author_held target_is_canon],
-          reject: %w[author_held],
-          converge: %w[zone_writable_by],
-        }.freeze
-
-        def self.for(transition) = BASE.fetch(transition, [])
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/evaluation.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # Immutable context handed to every predicate. `manifest` is the
-      # manifest (pure, no I/O); `envelope` is the entry under evaluation
-      # (nil when no bytes exist yet, e.g. a fresh put). `origin`/`target`
-      # are dotted keys; `transition` is the verb symbol.
-      Evaluation = Data.define(
-        :actor, :transition, :origin, :target, :envelope, :manifest
-      )
-    end
-  end
-end

data/lib/textus/domain/policy/guard.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # An ordered list of pure predicates over one Evaluation (ADR 0031).
-      # check! short-circuits on the first failing predicate that defines a
-      # bespoke #error (only zone_writable_by → WriteForbidden, the product's
-      # legible topology refusal); every other failure accumulates into
-      # GuardFailed naming the unmet predicate(s).
-      class Guard
-        attr_reader :predicates
-
-        def initialize(predicates)
-          @predicates = predicates
-        end
-
-        def check!(eval)
-          accumulated = []
-          @predicates.each do |pred|
-            next if pred.call(eval)
-            raise pred.error(eval) if pred.respond_to?(:error)
-
-            accumulated << [pred.name, pred.reason]
-          end
-          raise Textus::GuardFailed.new(accumulated) unless accumulated.empty?
-        end
-
-        def explain(eval)
-          @predicates.map { |p| [p.name, p.call(eval), p.reason] }
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/guard_factory.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      # Builds the effective Guard for (transition, key): base floor ++
-      # the predicates declared under rules[].guard[transition]. The single
-      # place the closed floor and the open ceiling are composed.
-      class GuardFactory
-        def initialize(manifest:, schemas:, extra: {})
-          @manifest = manifest
-          @schemas  = schemas
-          @extra    = extra # transient per-call params, e.g. { if_etag: "..." }
-        end
-
-        def for(transition, key)
-          specs = BaseGuards.for(transition) + composed(transition, key)
-          predicates = specs.map { |spec| build(spec) }.uniq(&:name)
-          Guard.new(predicates)
-        end
-
-        private
-
-        def composed(transition, key)
-          guard_map = @manifest.rules.for(key).guard
-          return [] if guard_map.nil?
-
-          Array(guard_map[transition.to_s])
-        end
-
-        def build(spec)
-          # etag_match takes a per-call param rather than a manifest one.
-          return Predicates::EtagMatch.new(if_etag: @extra[:if_etag]) if spec == "etag_match"
-
-          Predicates::Registry.build(spec, schemas: @schemas)
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/handler_allowlist.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      class HandlerAllowlist
-        attr_reader :handlers
-
-        def initialize(handlers:)
-          @handlers = Array(handlers).map(&:to_s).freeze
-        end
-
-        def allows?(handler)
-          @handlers.include?(handler.to_s)
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/author_held.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Predicate: the acting role must hold the 'author' capability in the
-        # active manifest (ADR 0030 capability roles). Folds in the old
-        # Write::AuthorityGate so accept/reject and rules[].guard share one
-        # implementation. No bespoke #error — failures accumulate into
-        # GuardFailed (ADR 0031).
-        class AuthorHeld
-          attr_reader :reason
-
-          def name = "author_held"
-
-          def call(eval)
-            holders = eval.manifest.policy.roles_with_capability("author")
-            return true if holders.include?(eval.actor.to_s)
-
-            @reason =
-              if holders.empty?
-                "no role holds the 'author' capability; #{eval.transition} is disabled"
-              else
-                "role '#{eval.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
-              end
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy/predicates/etag_match.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Advisory pre-flight etag check for policy explain. The
-        # authoritative compare-and-write stays in Envelope::IO::Writer
-        # (atomic write-then-audit, ADR 0017). Passes when no if_etag is
-        # supplied (params[:if_etag] nil) — guard does not require it.
-        class EtagMatch
-          attr_reader :reason
-
-          def initialize(if_etag: nil)
-            @if_etag = if_etag
-          end
-
-          def name = "etag_match"
-
-          def call(eval)
-            return true if @if_etag.nil?
-            return true if eval.envelope.nil? # creating; Writer handles race
-            return true if eval.envelope.etag == @if_etag
-
-            @reason = "etag mismatch: wanted #{@if_etag}, have #{eval.envelope.etag}"
-            false
-          end
-        end
-      end
-    end
-  end
-end