Module: Textus::CLI::Runner

Defined in:
lib/textus/cli/runner.rb

Overview

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).

Defined Under Namespace

Classes: Base

Constant Summary collapse

BEHAVIORAL_HATCHES =

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   — IntakeFetch read-through orchestration on --fetch
build — auto-resolves the build-capability actor role (not --as) and
        serializes under BuildLock; the role resolution is policy, not
        a projection (around: covers only the lock)

%i[get put build].freeze
NON_PROJECTED_CLI =

Contract verbs whose CLI is a plain ‘< Verb` command, not a projection at all — worker verbs and composite reports assembled outside the contract:

fetch, fetch_all — background intake workers (not request/response)
boot, doctor     — composite reports

%i[fetch fetch_all boot doctor].freeze
HAND_AUTHORED_VERBS =

The installer skips generation for either category.

(BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze

Class Method Summary collapse

Class Method Details

.apply_cli_defaults(spec, inputs) ⇒ Object

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/zone_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.



76
77
78
79
80
81
82
 
# File 'lib/textus/cli/runner.rb', line 76

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

.coerce(arg, raw) ⇒ Object

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.



113
114
115
116
117
118
 
# File 'lib/textus/cli/runner.rb', line 113

def coerce(arg, raw)
  return effective_default(arg) != true if arg.type == :boolean
  return Integer(raw) if arg.type == Integer

  raw
end

.dispatch(verb_instance, store, spec) ⇒ Object

Normalize parsed CLI input into the uniform by-name inputs hash and dispatch through RoleScope’s single bind+invoke site. A missing required arg becomes a UsageError phrased in the operator’s command path (parity with the hand-written verbs).



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/textus/cli/runner.rb', line 55

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)
  scope = verb_instance.session_for(store)
  begin
    result = scope.dispatch_bound(spec.verb, inputs)
  rescue Textus::Contract::MissingArgs => e
    raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
  end
  verb_instance.emit(shape(spec, result, inputs))
end

.effective_default(arg) ⇒ Object

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, zone_mv) gets a `–dry-run` flag, not `–no-dry-run`.



97
98
99
 
# File 'lib/textus/cli/runner.rb', line 97

def effective_default(arg)
  arg.cli_default == :__unset ? arg.default : arg.cli_default
end

.ensure_group(name) ⇒ Object 



120
121
122
123
124
125
126
127
 
# File 'lib/textus/cli/runner.rb', line 120

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

.flagspec_for(arg) ⇒ Object 



101
102
103
104
105
106
107
108
 
# File 'lib/textus/cli/runner.rb', line 101

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

.hand_authored?(verb) ⇒ Boolean

Returns:

  • (Boolean) 


148
 
# File 'lib/textus/cli/runner.rb', line 148

def hand_authored?(verb) = HAND_AUTHORED_VERBS.include?(verb)

.install! ⇒ Object 



150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/textus/cli/runner.rb', line 150

def install!
  @installed ||= {}
  Textus::Dispatcher::VERBS.each_value do |klass|
    next unless klass.respond_to?(:contract?) && klass.contract?

    spec = klass.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

.install_for(spec) ⇒ Object 



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/textus/cli/runner.rb', line 165

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

.shape(spec, result, inputs) ⇒ Object

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).



88
89
90
 
# File 'lib/textus/cli/runner.rb', line 88

def shape(spec, result, inputs)
  Textus::Contract::View.render(spec, :cli, result, inputs)
end