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.

%i[].freeze
HAND_AUTHORED_VERBS =

The installer skips generation for either category.

(BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze
STDIN_VERBS = 
%i[propose].freeze
CLI_PATHS = 
{
  uid: "key uid",
  key_mv_prefix: "key mv-prefix",
  key_delete_prefix: "key delete-prefix",
}.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.



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

def apply_cli_defaults(spec, inputs)
  spec.args.each_with_object(inputs.dup) do |a, h|
    next if a.cli_default.nil? || 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.



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

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
66
 
# File 'lib/textus/surface/cli/runner.rb', line 52

def dispatch(verb_instance, store, spec)
  inputs = Textus::Protocol::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 verb_instance.class.stdin_json
  inputs = Surface::CLI::Sources.acquire(spec, inputs)
  inputs = apply_cli_defaults(spec, inputs)
  role = verb_instance.resolved_role(store)

  s = store.with_role(role)
  result = Textus::Surface::Dispatch.call(s, spec.verb, **inputs)
  verb_instance.emit(result)
rescue Textus::Protocol::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.



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

def effective_default(arg)
  arg.cli_default.nil? ? arg.default : arg.cli_default
end

.ensure_group(name) ⇒ Object 



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

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 



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

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) 


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

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

.install! ⇒ Object 



137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/textus/surface/cli/runner.rb', line 137

def install!
  @installed ||= {}
  Textus::Protocol::VerbRegistry.registered.each do |spec|
    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 



156
157
158
159
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 156

def install_for(spec)
  cli_path = CLI_PATHS[spec.verb] || spec.cli_path
  cli_words = cli_path.split
  group_name = cli_words.size > 1 ? cli_words.first : nil
  group = group_name ? ensure_group(group_name) : nil
  leaf = cli_words.last
  non_positional = spec.args.reject(&:positional)

  klass = Class.new(Base)
  klass.spec = spec
  klass.stdin_json = STDIN_VERBS.include?(spec.verb)
  klass.command_name leaf
  klass.parent_group group if group
  klass.option :as_flag, "--as=ROLE"
  klass.option :use_stdin, "--stdin" if klass.stdin_json
  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