Module: Textus::Surface::CLI::Runner

Defined in:
lib/textus/surface/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   — reads the entry JSON from --stdin (ADR 0089: just stores bytes,
        no --fetch transform)

(build removed in ADR 0087: materialization is system-pushed via drain/serve)

%i[get put].freeze
NON_PROJECTED_CLI =

Contract verbs whose CLI is a plain ‘< Verb` command, not a projection at all — composite reports assembled outside the contract. (boot removed: its contract carries surfaces :cli + the :lean arg, so the generic projection now generates it; the hand-authored CLI::Verb::Boot is deleted in ADR 0101.) (doctor retained: hand-authored to preserve –check=NAME flag spelling and the exit_code: res ? 0 : 1 behavior — two things the generic projection cannot yet express; kept in ADR 0101 pending a future pass.) (fetch/fetch_all were removed in ADR 0079: Produce::Acquire::Intake is now internal, driven by the converge sweep (drain/serve) and hook run — ADR 0089 removed the read-through that once also drove it.)

%i[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/data_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.



72
73
74
75
76
77
78
 
# File 'lib/textus/surface/cli/runner.rb', line 72

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.



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

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

  raw
end

.dispatch(verb_instance, store, spec) ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/textus/surface/cli/runner.rb', line 52

def dispatch(verb_instance, store, spec)
  inputs = Textus::Gate::Binder.inputs_from_ordered(
    spec, verb_instance.positional, verb_instance.flag_values(spec)
  )
  inputs = inputs.merge(Surface::CLI::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
  inputs = Surface::CLI::Sources.acquire(spec, inputs)
  inputs = apply_cli_defaults(spec, inputs)
  role = verb_instance.resolved_role(store)

  result = store.gate.dispatch(spec:, inputs:, role:, surface: :cli)
  verb_instance.emit(result)
rescue Textus::Gate::MissingArgs => e
  raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
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, data_mv) gets a `–dry-run` flag, not `–no-dry-run`.



85
86
87
 
# File 'lib/textus/surface/cli/runner.rb', line 85

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

.ensure_group(name) ⇒ Object 



109
110
111
112
113
114
115
116
 
# File 'lib/textus/surface/cli/runner.rb', line 109

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 



89
90
91
92
93
94
95
96
 
# File 'lib/textus/surface/cli/runner.rb', line 89

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) 


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

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

.install! ⇒ Object 



145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/textus/surface/cli/runner.rb', line 145

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

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



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/textus/surface/cli/runner.rb', line 160

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