reason_me_this 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4df9a831994e4b534a9aaeb9fcf9f014414723658d37bb682069bc2fddae6511
+  data.tar.gz: 9ce6fa1cafeff01a49479e5019fe1985d844985dddf526010ef42ab019d70c28
+SHA512:
+  metadata.gz: 7ddb5ae04b29565f4a4931593c804f9b61de5dd5ef49bbc2b57ac1c0ab731fa88ff52abbb996f3213d194a01a3b336d90298df16e20fb68bb02c255580af5e16
+  data.tar.gz: 221f7838a5d8c03fe7385ab3cc67b396e79ce35ed8050dba0440aebd462c91a9023d22db9dd3d33d1ca3f69fb605e16cf83f800e3cf9b62f896ee77421ab2464

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rhys Murray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,199 @@
+# reason_me_this
+
+The Ruby client for [Reason Me This](https://reason-me-this.com). It runs, explains, pushes and publishes definitions over HTTP
+and keeps every number exact on the way out and on the way back.
+
+It only speaks HTTP: it needs nothing beyond Ruby's standard library and does not load the engine.
+
+## Install
+
+```ruby
+gem "reason_me_this"
+```
+
+## The rmt CLI
+
+The gem installs `rmt`, which builds, proves, publishes and runs blueprints on the service. It answers in
+JSON when its output is not a terminal, so an agent can loop on it, and in text at a terminal.
+
+```sh
+export RMT_API_KEY=...                       # from https://reason-me-this.com/app/api_keys
+rmt guide                                    # how to build a blueprint
+rmt check bill.yml                           # exit 2 while it has problems
+rmt test bill.yml cases.yml                  # exit 3 while a case fails
+rmt push bill bill.yml cases.yml && rmt publish bill
+echo '{"plan": "flat_rate"}' | rmt run bill --trace
+rmt run electricity_bill --facts facts.json  # a shipped blueprint, by name
+```
+
+`check`, `test` and `run` on a file send its text to the service and save nothing. Exit codes: 0 success,
+1 a run failed, 2 problems, 3 a case failed, 64 usage, 69 the service could not be reached, 77 the key was
+refused. `rmt help` lists every command. `RMT_API_URL` points it at another service.
+
+## Configure
+
+```ruby
+require "reason_me_this"
+
+ReasonMeThis.configure do |config|
+  config.url = ENV["RMT_API_URL"]     # https://reason-me-this.com/api
+  config.api_key = ENV["RMT_API_KEY"]
+end
+```
+
+In Rails this belongs in `config/initializers/reason_me_this.rb`.
+
+## Run
+
+```ruby
+answer = ReasonMeThis.run("sales_commission@3", facts, calculation: :year)
+
+answer.total_paid        # => BigDecimal("55830")
+answer[:by_quarter]      # => [{start: Date(2026-01-01), payout: BigDecimal("5000"), ...}, ...]
+answer.to_h
+```
+
+| Option | Means |
+| --- | --- |
+| `calculation:` | which calculation in the definition to run |
+| `version:` | a published version number, `"latest"` (the default) or `"draft"` |
+| `trace:` | `true` answers as `explain` does |
+
+`"sales_commission@3"` pins the name to published version 3. A `version:` given as well wins over the pin.
+
+### What comes back
+
+The service sends numbers as strings so they stay exact. An answer reads them back:
+
+| The service sends | You get |
+| --- | --- |
+| `"55830"`, `"0.8"`, `"-12.5"` | `BigDecimal` |
+| `"2026-07-01"` | `Date` |
+| any other string, number, `true`, `false`, `null` | as sent |
+| an object | a hash with symbol keys, its values read the same way |
+
+A text output that happens to look like a number (an id of `"1042"`) is read as a number too.
+
+### What goes out
+
+Facts go out exactly as you hold them: a `BigDecimal` is written as a JSON number in full, never rounded
+through a `Float` or quoted as a string, and a `Date` or `Time` as an ISO 8601 string. Use `BigDecimal` for
+money and rates; a `Float` goes out as Ruby writes it.
+
+## Explain
+
+```ruby
+explained = ReasonMeThis.explain("sales_commission", facts, calculation: :year)
+
+explained.outputs      # an answer, as run gives
+explained.steps        # each step with its value, in the order they ran
+```
+
+## Manage definitions
+
+```ruby
+ReasonMeThis.push("bill", yaml: File.read("bill.yml"), cases: File.read("cases.yml"))
+# => {problems: [], passed: 4, failed: 0, cases: [...]}
+
+ReasonMeThis.publish("bill")        # => 4, the new version
+ReasonMeThis.definitions            # => [{name: "bill", published_version: 4, updated_at: "..."}]
+ReasonMeThis.definition("bill")     # => {name: "bill", yaml: "...", cases: "...", published_version: 4}
+```
+
+## Errors
+
+Every error is a `ReasonMeThis::Error`, with a message in plain words.
+
+| Error | When |
+| --- | --- |
+| `Unauthorized` | the service refused the API key (401) |
+| `NotFound` | no such definition or version (404) |
+| `InvalidFacts` | the facts have problems (422); `#problems` lists them |
+| `StepFailed` | a step failed while running (422); the message says which |
+| `Timeout` | the run took too long on the service (503) |
+| `Unreachable` | the service could not be reached: refused, DNS, or timed out |
+| `Rejected` | `push` or `publish` was refused: problems in the definition or failing cases; `#report` has them |
+
+```ruby
+begin
+  ReasonMeThis.run("bill", facts)
+rescue ReasonMeThis::InvalidFacts => e
+  e.problems   # => ["hours is missing"]
+end
+```
+
+## In a model
+
+`ReasonMeThis::Model` works in any class, ActiveRecord or not.
+
+```ruby
+class Rep < ApplicationRecord
+  include ReasonMeThis::Model
+
+  reasons :statement, with: "sales_commission@3", calculation: :year do |year|
+    {deals: deals.closed_in(year).map(&:to_fact), quarters: quarter_targets.in(year).map(&:to_fact)}
+  end
+end
+
+rep.statement(2026)               # => an answer, remembered on this rep for these arguments
+rep.statement(2026).total_paid
+rep.statement_explained(2026)     # the same run, explained
+```
+
+The block runs on the instance, takes the method's arguments, and returns the facts.
+
+## More than one service
+
+Build a client for each service and use it as you would the module:
+
+```ruby
+client = ReasonMeThis::Client.new(url: tenant.rmt_url, api_key: tenant.rmt_key)
+client.run("sales_commission", facts, calculation: :year)
+```
+
+A model runs on `reason_me_this_client`, which is the configured client unless you say otherwise:
+
+```ruby
+class Rep < ApplicationRecord
+  include ReasonMeThis::Model
+
+  def reason_me_this_client = tenant.reason_me_this_client
+end
+```
+
+## In tests
+
+A client talks through a connection: anything with `request(method, path, body)` that answers
+`[status, parsed_json]`. Give it a fake to run offline:
+
+```ruby
+class FakeConnection
+  def initialize(body) = @body = body
+  def request(_method, _path, _body = nil) = [200, @body]
+end
+
+ReasonMeThis.configure { |config| config.connection = FakeConnection.new("total_paid" => "55830") }
+```
+
+## Against a local service
+
+Run the service on port 3000, make an API key there, then:
+
+```sh
+export RMT_API_URL=http://localhost:3000/api
+export RMT_API_KEY=your-key
+bundle exec ruby -Ilib -r reason_me_this -e 'ReasonMeThis.configure { |c| c.url = ENV["RMT_API_URL"]; c.api_key = ENV["RMT_API_KEY"] }; p ReasonMeThis.definitions'
+```
+
+## Example
+
+`examples/commissions` is a small Rails app that shows a sales rep's commission statement by quarter, worked
+out by the service from the rep's deals. See its README.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```

data/exe/rmt

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'reason_me_this/cli'
+
+exit ReasonMeThis::CLI.call(ARGV)

data/lib/reason_me_this/answer.rb

@@ -0,0 +1,17 @@
+module ReasonMeThis
+  class Answer
+    def initialize(outputs)
+      @outputs = Values.read(outputs)
+    end
+
+    def [](name) = @outputs[name.to_sym]
+
+    def to_h = @outputs
+
+    def method_missing(name, *args)
+      args.empty? && @outputs.key?(name) ? @outputs[name] : super
+    end
+
+    def respond_to_missing?(name, include_private = false) = @outputs.key?(name) || super
+  end
+end

data/lib/reason_me_this/cli/output.rb

@@ -0,0 +1,169 @@
+module ReasonMeThis
+  class CLI
+    module Output
+      def self.for(out, format)
+        terminal = out.respond_to?(:tty?) && out.tty?
+        return Json.new(out) if (format || (terminal ? :text : :json)) == :json
+
+        Text.new(out, colour: terminal && !ENV.key?('NO_COLOR'))
+      end
+
+      class Json
+        def initialize(out)
+          @out = out
+        end
+
+        def show(_kind, payload, **)
+          @out.puts(JSON.pretty_generate(payload))
+        end
+      end
+
+      class Text
+        def initialize(out, colour:)
+          @out = out
+          @colour = colour
+        end
+
+        def show(kind, payload, **context)
+          @out.puts(send(kind, symbolized(payload), **context))
+        end
+
+        private
+
+        def symbolized(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.to_sym, symbolized(item)] }
+          when Array then value.map { |item| symbolized(item) }
+          else value
+          end
+        end
+
+        def outputs(values) = fields(values, 0).join("\n")
+
+        def trace(explained)
+          [outputs(explained[:outputs]), '', bold('How it was worked out'), *steps(explained[:steps], 1)].join("\n")
+        end
+
+        def problems(answer)
+          listed = answer[:problems]
+          return pass('No problems') if listed.empty?
+
+          [fail("#{listed.size} #{listed.size == 1 ? 'problem' : 'problems'}"), *listed.map { |problem| "  • #{problem}" }].join("\n")
+        end
+
+        def error(answer) = fail(answer[:error])
+
+        def refusal(answer) = answer.key?(:problems) ? problems(answer) : error(answer)
+
+        def report(answer)
+          answer.key?(:error) || answer[:problems]&.any? ? refusal(answer) : cases(answer)
+        end
+
+        def cases(answer)
+          passed, failed = answer.values_at(:passed, :failed).map(&:to_i)
+          failing = answer[:cases].reject { |result| result[:passed] }
+          return pass("#{passed} #{passed == 1 ? 'case' : 'cases'} passed") if failing.empty?
+
+          [fail("#{failed} of #{passed + failed} cases failed"), *failing.flat_map { |result| failed_case(result) }].join("\n")
+        end
+
+        def failed_case(result)
+          detail = if result[:error]
+                     ["      #{result[:error]}"]
+                   else
+                     result[:differences].map { |d| "      #{d[:output]}: expected #{d[:expected]}, got #{d[:actual]}" }
+                   end
+          ['', "  #{fail(result[:name])}", *detail]
+        end
+
+        def published(answer, name:) = pass("Published #{name} v#{answer[:version]}")
+
+        def definitions(answer)
+          rows = answer[:definitions].map do |definition|
+            [definition[:name], definition[:published_version] ? "v#{definition[:published_version]}" : 'draft only', definition[:updated_at].to_s[0, 10]]
+          end
+          table([%w[NAME PUBLISHED UPDATED], *rows]).join("\n")
+        end
+
+        def created(answer) = answer[:created].map { |path| "Wrote #{path}" }.join("\n")
+
+        def describe(answer)
+          types = answer[:steps].map { |name, type| "  #{name.to_s.ljust(10)} #{type[:purpose]}" }
+          functions = answer[:formulas][:usage].map { |_name, usage| "  #{usage}" }
+          [bold('Step types'), *types, '', bold('Formula functions'), *functions, '',
+           'Run rmt describe --json for an example of each, with what it gives, or rmt guide for the whole guide.'].join("\n")
+        end
+
+        def fields(values, depth)
+          width = values.keys.map { |name| name.to_s.size }.max
+          values.flat_map do |name, value|
+            label = "#{'  ' * depth}#{name}"
+            case value
+            when Hash then [label, *fields(value, depth + 1)]
+            when Array then list(label, value, width, depth)
+            else "#{label.ljust(width + (2 * depth))}  #{value}"
+            end
+          end
+        end
+
+        def list(label, value, width, depth)
+          return ["#{label.ljust(width + (2 * depth))}  #{value.join(', ')}"] unless rows?(value)
+
+          [label, *table(columns(value)).map { |line| "#{'  ' * (depth + 1)}#{line}" }]
+        end
+
+        def rows?(list) = list.any? && list.all?(Hash)
+
+        def columns(rows)
+          names = rows.flat_map(&:keys).uniq
+          [names.map(&:to_s), *rows.map { |row| names.map { |name| cell(row[name]) } }]
+        end
+
+        def cell(value) = value.is_a?(Array) || value.is_a?(Hash) ? value.size.to_s : value.to_s
+
+        def table(lines)
+          widths = lines.transpose.map { |column| column.map { |cell| cell.to_s.size }.max }
+          lines.map { |line| line.each_with_index.map { |cell, index| cell.to_s.ljust(widths[index]) }.join('  ').rstrip }
+        end
+
+        def steps(list, depth)
+          lines = list.map { |step| ["#{'  ' * depth}#{step[:step]}", summary(step[:value], step[:of]), detail(step)] }
+          names = lines.map { |name, *| name.size }.max
+          values = lines.select(&:last).map { |_, value, _| value.size }.max
+          list.zip(lines).flat_map { |step, line| [step_line(*line, names, values), *step_rows(step, depth)] }
+        end
+
+        def step_line(name, value, detail, names, values)
+          detail ? "#{name.ljust(names)}  #{value.ljust(values)}  #{detail}" : "#{name.ljust(names)}  #{value}"
+        end
+
+        def step_rows(step, depth)
+          Array(step[:rows]).each_with_index.flat_map { |row, index| ["#{'  ' * (depth + 1)}row #{index + 1}", *steps(row, depth + 2)] }
+        end
+
+        def summary(value, over)
+          return "#{value.size} #{value.size == 1 ? 'row' : 'rows'}#{" over #{over}" if over}" if value.is_a?(Array)
+
+          value.is_a?(Hash) ? value.map { |name, item| "#{name} #{item}" }.join(', ') : value.to_s
+        end
+
+        def detail(step)
+          return dim(step[:formula]) if step[:formula]
+          return dim("row #{step[:row].map { |name, value| "#{name} #{value}" }.join(', ')}") if step[:row]
+
+          dim("from #{step[:of]}") if step[:of] && !step[:value].is_a?(Array)
+        end
+
+        def pass(message) = paint("✓ #{message}", 32)
+
+        def fail(message) = paint("✗ #{message}", 31)
+
+        def bold(text) = paint(text, 1)
+
+        def dim(text) = paint(text, 2)
+
+        def paint(text, code) = @colour ? "\e[#{code}m#{text}\e[0m" : text
+      end
+    end
+  end
+end

data/lib/reason_me_this/cli.rb

@@ -0,0 +1,243 @@
+require 'json'
+require 'fileutils'
+require 'optparse'
+require 'reason_me_this'
+require 'reason_me_this/cli/output'
+
+module ReasonMeThis
+  class CLI
+    HOSTED = 'https://reason-me-this.com/api'.freeze
+    KEYS = 'https://reason-me-this.com/app/api_keys'.freeze
+
+    USAGE = <<~TEXT.freeze
+      Usage: rmt COMMAND [arguments] [options]
+
+      Build and prove a blueprint:
+        guide                                   print the guide to building a blueprint
+        describe                                list step types with examples and the functions formulas can call
+        check BLUEPRINT                         list problems with a blueprint file
+        test BLUEPRINT CASES                    run each case's facts and compare the expected outputs
+        run BLUEPRINT [--facts FILE] [--calculation NAME] [--trace]
+                                                run a blueprint file; facts come from FILE or standard input
+
+      Publish and run definitions:
+        push NAME BLUEPRINT [CASES]             save a definition's draft, checked and tested
+        publish NAME                            publish the draft as the next version
+        run NAME [--version N|draft] [...]      run a definition, or a shipped blueprint, by name
+        list                                    list the definitions and their published versions
+        pull NAME [--dir DIR]                   write DIR/NAME/blueprint.yml and cases.yml
+
+      A BLUEPRINT ending in .yml or .yaml or containing a / is a file; anything else is a name.
+      Every command but guide and describe needs RMT_API_KEY (create one at #{KEYS}).
+      RMT_API_URL defaults to #{HOSTED}.
+
+      Options for any command:
+        --json                                  answer in JSON (the default when output is not a terminal)
+        --text                                  answer in text (the default at a terminal)
+
+      Exit codes: 0 success, 1 a run failed, 2 the blueprint has problems, 3 a case failed, 64 usage,
+      69 the service could not be reached, 77 the service refused the key
+    TEXT
+
+    WORKFLOW = <<~MARKDOWN.freeze
+      # Building a blueprint
+
+      A blueprint is a YAML file describing calculations as data. You can turn a source document (a rulebook
+      chapter, a price list, a policy) into a blueprint, prove it against worked examples, and run it.
+
+      ## Workflow
+
+      1. Run `rmt describe` to see every step type with an example, and the functions formulas can call.
+      2. Read the source and list the outputs it asks for and the facts they depend on.
+      3. Write worked examples first, in a cases file, from figures in the source where it gives them. Work out
+         others by hand and say so in the case name.
+      4. Write the blueprint.
+      5. Run `rmt check BLUEPRINT` until it prints no problems.
+      6. Run `rmt test BLUEPRINT CASES` until every case passes. Change the blueprint, not the cases,
+         unless a case was worked out wrongly.
+      7. Run `rmt run BLUEPRINT --facts FACTS.json` for new facts. Add `--trace` to see how every step
+         was reached when a value surprises you.
+      8. `rmt push NAME BLUEPRINT CASES` saves it as the draft of the definition NAME, and `rmt publish NAME`
+         makes the draft the next version, which applications call. A draft with problems or a failing case
+         is refused.
+
+      Every command prints JSON to standard output when it is not a terminal, which is how an agent runs it,
+      and text at a terminal; `--json` or `--text` chooses either way. Exit codes: 0 success, 1 a run failed,
+      2 the blueprint has problems, 3 a case failed, 64 usage, 69 the service could not be reached, 77 the
+      service refused the key. A blueprint imports others by name (`imports: [rates]`, `rates@2`,
+      `rates@draft`), never by path.
+
+    MARKDOWN
+
+    def self.call(argv, env: ENV, connection: nil, **io)
+      key = env['RMT_API_KEY'].to_s
+      connection ||= Connection.new(env['RMT_API_URL'].to_s.empty? ? HOSTED : env['RMT_API_URL'], key)
+      new(out: io.fetch(:out, $stdout), err: io.fetch(:err, $stderr), input: io.fetch(:input, $stdin), connection:, keyed: !key.empty?).call(argv.dup)
+    end
+
+    def initialize(out:, err:, input:, connection:, keyed:)
+      @out = out
+      @err = err
+      @input = input
+      @connection = connection
+      @keyed = keyed
+    end
+
+    def call(argv)
+      @output = Output.for(@out, format(argv))
+      command = argv.shift
+      return help(argv.first) if command == 'help'
+      return help(command) if argv.delete('--help')
+
+      dispatch(command, argv)
+    rescue OptionParser::ParseError, Errno::ENOENT => e
+      @err.puts(e.message)
+      usage
+    end
+
+    private
+
+    def dispatch(command, argv)
+      case command
+      when 'guide', 'describe', 'list' then send(command)
+      when 'check', 'test', 'run', 'push', 'publish', 'pull' then argv.first ? send(command, argv) : usage
+      else usage
+      end
+    end
+
+    def format(argv)
+      chosen = %w[--json --text].select { |flag| argv.delete(flag) }
+      chosen.last&.delete_prefix('--')&.to_sym
+    end
+
+    def guide
+      on_service(:get, '/describe', keyless: true) do |_status, answer|
+        @out.print(WORKFLOW, answer['guide'])
+        0
+      end
+    end
+
+    def describe
+      on_service(:get, '/describe', keyless: true) { |_status, answer| answered(:describe, answer.except('guide'), 0) }
+    end
+
+    def check(argv)
+      on_service(:post, '/check', {yaml: File.read(argv.first)}) do |_status, answer|
+        answered(:problems, answer.slice('problems'), answer['problems'].any? ? 2 : 0)
+      end
+    end
+
+    def test(argv)
+      return usage unless argv[1]
+
+      on_service(:post, '/check', {yaml: File.read(argv[0]), cases: File.read(argv[1])}) { |_status, answer| answered(:report, answer, proven(answer)) }
+    end
+
+    def run(argv)
+      options = {}
+      OptionParser.new do |parser|
+        parser.on('--facts FILE') { |file| options[:facts] = file }
+        parser.on('--calculation NAME') { |name| options[:calculation] = name }
+        parser.on('--version VERSION') { |version| options[:version] = version }
+        parser.on('--trace') { options[:trace] = true }
+      end.parse!(argv)
+      facts = read_facts(options) or return 1
+      body = {facts:, **options.slice(:calculation, :version, :trace)}
+      return ran(:post, "/definitions/#{argv.first}/run", body, options) unless path?(argv.first)
+
+      ran(:post, '/try', {yaml: File.read(argv.first), **body.except(:version)}, options)
+    end
+
+    def ran(method, path, body, options)
+      on_service(method, path, body) do |status, answer|
+        if status == 200
+          answered(options[:trace] ? :trace : :outputs, answer, 0)
+        else
+          answered(:refusal, answer, 1)
+        end
+      end
+    end
+
+    def read_facts(options)
+      JSON.parse(options[:facts] ? File.read(options[:facts]) : @input.read, decimal_class: BigDecimal)
+    rescue JSON::ParserError => e
+      answered(:problems, {'problems' => ["The facts are not valid JSON: #{e.message}"]}, 1)
+      nil
+    end
+
+    def push(argv)
+      name, blueprint, cases = argv
+      return usage unless blueprint
+
+      body = {yaml: File.read(blueprint), cases: cases ? File.read(cases) : ''}
+      on_service(:put, "/definitions/#{name}", body) { |_status, answer| answered(:report, answer, proven(answer)) }
+    end
+
+    def publish(argv)
+      on_service(:post, "/definitions/#{argv.first}/publish") do |status, answer|
+        status == 201 ? answered(:published, answer, 0, name: argv.first) : answered(:report, answer, proven(answer))
+      end
+    end
+
+    def list
+      on_service(:get, '/definitions') { |status, answer| status == 200 ? answered(:definitions, answer, 0) : answered(:refusal, answer, 1) }
+    end
+
+    def pull(argv)
+      options = {dir: '.'}
+      OptionParser.new { |parser| parser.on('--dir DIR') { |dir| options[:dir] = dir } }.parse!(argv)
+      name = argv.first
+      on_service(:get, "/definitions/#{name}") do |status, answer|
+        next answered(:refusal, answer, 1) unless status == 200
+
+        write_new({'blueprint.yml' => answer['yaml'], 'cases.yml' => answer['cases']}.transform_keys { |file| File.join(options[:dir], name, file) })
+      end
+    end
+
+    def write_new(files)
+      existing = files.keys.select { |path| File.exist?(path) }
+      return answered(:problems, {'problems' => existing.map { |path| "#{path} already exists" }}, 1) if existing.any?
+
+      files.each do |path, content|
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+      end
+      answered(:created, {'created' => files.keys}, 0)
+    end
+
+    def on_service(method, path, body = nil, keyless: false)
+      return answered(:problems, {'problems' => ["#{path} needs an API key: create one at #{KEYS} and set RMT_API_KEY"]}, 64) unless keyless || @keyed
+
+      status, answer = @connection.request(method, path, body)
+      return answered(:refusal, answer, 77) if [401, 403].include?(status)
+
+      yield(status, answer)
+    rescue Unreachable => e
+      answered(:refusal, {'error' => e.message}, 69)
+    end
+
+    def proven(answer)
+      return 1 unless answer.key?('problems')
+      return 2 if answer['problems'].any?
+
+      answer['failed'].to_i.positive? ? 3 : 0
+    end
+
+    def path?(argument) = argument.end_with?('.yml', '.yaml') || argument.include?('/')
+
+    def answered(kind, answer, code, context = {})
+      @output.show(kind, answer, **context)
+      code
+    end
+
+    def help(_command)
+      @out.puts(USAGE)
+      0
+    end
+
+    def usage
+      @err.puts(USAGE)
+      64
+    end
+  end
+end

data/lib/reason_me_this/configuration.rb

@@ -0,0 +1,3 @@
+module ReasonMeThis
+  Configuration = Struct.new(:url, :api_key, :connection)
+end

data/lib/reason_me_this/connection.rb

@@ -0,0 +1,41 @@
+require 'json'
+require 'net/http'
+require 'openssl'
+
+module ReasonMeThis
+  class Connection
+    def initialize(url, api_key)
+      @url = url.to_s.chomp('/')
+      @api_key = api_key
+    end
+
+    def request(method, path, body = nil)
+      raise Error.new('no URL is configured for Reason Me This') if @url.empty?
+
+      uri = URI("#{@url}#{path}")
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 10, read_timeout: 60) do |http|
+        http.request(build(method, uri, body))
+      end
+      [response.code.to_i, parsed(response)]
+    rescue SystemCallError, SocketError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+      raise Unreachable.new("could not reach the service at #{@url}: #{e.message}")
+    end
+
+    private
+
+    def build(method, uri, body)
+      Net::HTTP.const_get(method.to_s.capitalize).new(uri).tap do |request|
+        request['Authorization'] = "Bearer #{@api_key}"
+        request['Content-Type'] = 'application/json'
+        request['Accept'] = 'application/json'
+        request.body = JSON.generate(Values.write(body)) if body
+      end
+    end
+
+    def parsed(response)
+      JSON.parse(response.body.to_s.empty? ? '{}' : response.body)
+    rescue JSON::ParserError
+      {'error' => "the service answered HTTP #{response.code} with something other than JSON"}
+    end
+  end
+end

data/lib/reason_me_this/errors.rb

@@ -0,0 +1,30 @@
+module ReasonMeThis
+  class Error < StandardError; end
+  class Unauthorized < Error; end
+  class NotFound < Error; end
+  class StepFailed < Error; end
+  class Timeout < Error; end
+  class Unreachable < Error; end
+
+  class Refused < Error
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super(message)
+    end
+
+    def problems = report.fetch(:problems, [])
+  end
+
+  class InvalidFacts < Refused
+    def message = "the facts have problems: #{problems.join('; ')}"
+  end
+
+  class Rejected < Refused
+    def message
+      failed = "#{report[:failed]} cases failed" if report[:failed].to_i.positive?
+      "the definition was not accepted: #{[*problems, failed].compact.join('; ')}"
+    end
+  end
+end

data/lib/reason_me_this/explanation.rb

@@ -0,0 +1,3 @@
+module ReasonMeThis
+  Explanation = Data.define(:outputs, :steps)
+end

data/lib/reason_me_this/model.rb

@@ -0,0 +1,21 @@
+module ReasonMeThis
+  module Model
+    def self.included(base) = base.extend(ClassMethods)
+
+    module ClassMethods
+      def reasons(name, with:, calculation: nil, &facts)
+        {name => :run, "#{name}_explained": :explain}.each do |method, call|
+          define_method(method) do |*args|
+            reasonings[[method, args]] ||= reason_me_this_client.public_send(call, with, instance_exec(*args, &facts), calculation:)
+          end
+        end
+      end
+    end
+
+    def reason_me_this_client = ReasonMeThis.default
+
+    private
+
+    def reasonings = @reasonings ||= {}
+  end
+end

data/lib/reason_me_this/values.rb

@@ -0,0 +1,48 @@
+require 'bigdecimal'
+require 'date'
+require 'json'
+require 'time'
+
+module ReasonMeThis
+  module Values
+    NUMBER = /\A-?\d+(\.\d+)?\z/
+    DATE = /\A\d{4}-\d{2}-\d{2}\z/
+
+    module_function
+
+    def read(value)
+      deep(value) do |leaf|
+        case leaf
+        when NUMBER then BigDecimal(leaf)
+        when DATE then date(leaf)
+        else leaf
+        end
+      end
+    end
+
+    # A decimal goes out as a JSON number written in full, so the service reads the value that was typed.
+    def write(value)
+      deep(value) do |leaf|
+        case leaf
+        when BigDecimal then JSON::Fragment.new(leaf.to_s('F'))
+        when Date, Time then leaf.iso8601
+        else leaf
+        end
+      end
+    end
+
+    def date(text)
+      Date.iso8601(text)
+    rescue Date::Error
+      text
+    end
+
+    def deep(value, &)
+      case value
+      when Hash then value.to_h { |key, item| [key.is_a?(String) ? key.to_sym : key, deep(item, &)] }
+      when Array then value.map { |item| deep(item, &) }
+      else yield value
+      end
+    end
+  end
+end

data/lib/reason_me_this/version.rb

@@ -0,0 +1,3 @@
+module ReasonMeThis
+  VERSION = '0.1.0'.freeze
+end

data/lib/reason_me_this.rb

@@ -0,0 +1,70 @@
+require 'reason_me_this/version'
+require 'reason_me_this/values'
+require 'reason_me_this/answer'
+require 'reason_me_this/errors'
+require 'reason_me_this/explanation'
+require 'reason_me_this/connection'
+require 'reason_me_this/configuration'
+require 'reason_me_this/model'
+require 'forwardable'
+
+module ReasonMeThis
+  class << self
+    extend Forwardable
+
+    def_delegators :default, :run, :explain, :push, :publish, :definitions, :definition
+
+    def configure
+      yield configuration
+      @default = nil
+    end
+
+    def configuration = @configuration ||= Configuration.new
+
+    def default = @default ||= Client.new(**configuration.to_h.compact)
+  end
+
+  class Client
+    def initialize(url: nil, api_key: nil, connection: Connection.new(url, api_key))
+      @connection = connection
+    end
+
+    def run(name, facts, calculation: nil, version: nil, trace: false)
+      name, pinned = name.to_s.split('@', 2)
+      version ||= pinned&.match?(/\A\d+\z/) ? Integer(pinned) : pinned
+      answer = request(:post, at(name, :run), {facts:, calculation:, version:, trace: (true if trace)}.compact)
+      trace ? Explanation.new(outputs: Answer.new(answer[:outputs]), steps: answer[:steps]) : Answer.new(answer)
+    end
+
+    def explain(name, facts, calculation: nil, version: nil) = run(name, facts, calculation:, version:, trace: true)
+
+    def push(name, yaml:, cases: '') = request(:put, at(name), {yaml:, cases:}, invalid: Rejected)
+
+    def publish(name) = request(:post, at(name, :publish), invalid: Rejected)[:version]
+
+    def definitions = request(:get, '/definitions')[:definitions]
+
+    def definition(name) = request(:get, at(name))
+
+    private
+
+    def at(name, *action) = ['/definitions', name, *action].join('/')
+
+    def request(method, path, body = nil, invalid: InvalidFacts)
+      status, answer = @connection.request(method, path, body)
+      answer = Values.read(answer)
+      status.between?(200, 299) ? answer : raise(refusal(status, answer, invalid))
+    end
+
+    def refusal(status, answer, invalid)
+      case [status, answer]
+      in [401, _] then Unauthorized.new('the service refused the API key')
+      in [404, {error:}] then NotFound.new(error)
+      in [422, {problems:}] then invalid.new(answer)
+      in [422, {error:}] then StepFailed.new(error)
+      in [503, {error:}] then Timeout.new(error)
+      else Error.new(["the service answered HTTP #{status}", answer[:error]].compact.join(': '))
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: reason_me_this
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rhys Murray
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.10'
+description: 'The client for reason-me-this.com: runs, explains, pushes and publishes
+  blueprints over HTTP, keeping numbers exact.'
+executables:
+- rmt
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/rmt
+- lib/reason_me_this.rb
+- lib/reason_me_this/answer.rb
+- lib/reason_me_this/cli.rb
+- lib/reason_me_this/cli/output.rb
+- lib/reason_me_this/configuration.rb
+- lib/reason_me_this/connection.rb
+- lib/reason_me_this/errors.rb
+- lib/reason_me_this/explanation.rb
+- lib/reason_me_this/model.rb
+- lib/reason_me_this/values.rb
+- lib/reason_me_this/version.rb
+homepage: https://reason-me-this.com
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://reason-me-this.com/docs/
+  source_code_uri: https://github.com/rhys117/reason-me-this
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Run, explain and publish Reason Me This blueprints from Ruby, and the rmt
+  CLI
+test_files: []