samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/parent_report.rb

@@ -3,6 +3,7 @@
 require "delegate"
 require "json"
 
+require_relative "chi_invocation"
 require_relative "cli/exit"
 require_relative "pending_question"
 require_relative "session"
@@ -81,7 +82,9 @@ module Samagotchi
     # @return [Hash] the --format json object
     # @param strategy [Guardrails::ParentPolicy::Strategy, nil] what a parent
     #   may pick on the waited-for session (#strategy_for); nil: config.yml's
-    def json(result, session_id:, timeout: nil, extra: {}, strategy: nil)
+    # @param via [ChiInvocation] how the printed commands are spelled (this
+    #   machine's chi, or chi --remote NAME); each function here takes it
+    def json(result, session_id:, timeout: nil, extra: {}, strategy: nil, via: ChiInvocation::HERE)
       report = { status: status(result), session_id: session_id }
       report[:turn_id] = result.turn_id unless result.turn_id.to_s.empty?
       case report[:status]
@@ -89,10 +92,10 @@ module Samagotchi
       when "question"
         question = question(result.question, strategy: strategy)
         report[:question] = question
-        report[:answer_with] = answer_with(session_id, question)
+        report[:answer_with] = answer_with(session_id, question, via: via)
       else
         report.merge!(stop_facts(result))
-        report[:detail] = detail(result, session_id: session_id, timeout: timeout, strategy: strategy)
+        report[:detail] = detail(result, session_id: session_id, timeout: timeout, strategy: strategy, via: via)
       end
       report.merge(extra)
     end
@@ -110,8 +113,8 @@ module Samagotchi
     end
 
     # @return [String] the JSON object as one line
-    def json_line(result, session_id:, timeout: nil, extra: {}, strategy: nil)
-      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy))
+    def json_line(result, session_id:, timeout: nil, extra: {}, strategy: nil, via: ChiInvocation::HERE)
+      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy, via: via))
     end
 
     # Print a wait's end the way the commands do: the JSON object on
@@ -120,17 +123,19 @@ module Samagotchi
     # @param command [String] "chi send", "chi answer"
     # @param extra [Hash] more keys for the JSON object (#json)
     # @return [Integer] the exit status
-    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {}, strategy: nil)
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {}, strategy: nil,
+               via: ChiInvocation::HERE)
       if json
-        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy))
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy, via: via))
       elsif result.status == :done
         stdout.puts(result.text)
       else
         stdout.flush
         text = if result.status == :waiting_for_answer
-                 question_text(result.question, session_id: session_id, strategy: strategy)
+                 question_text(result.question, session_id: session_id, strategy: strategy, via: via)
                else
-                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id, strategy: strategy)}\n"
+                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id, strategy: strategy,
+                                   via: via)}\n"
                end
         stderr.print("#{command}: #{text}")
       end
@@ -177,16 +182,22 @@ module Samagotchi
     # lists an Allow once a parent may give). A step-limit question's
     # continues the turn, or stops it where a parent may not continue (its
     # other form is in #question_text).
-    def answer_with(session_id, question)
-      return "chi answer #{session_id} --question #{question[:id]} --option Deny --text WHY" if approval?(question)
-      return stop_command(session_id, question) if continue?(question) && !may_continue?(question)
-      return "chi answer #{session_id} --question #{question[:id]} --option Continue" if continue?(question)
+    def answer_with(session_id, question, via: ChiInvocation::HERE)
+      return answer_command(session_id, question, "Deny --text WHY", via: via) if approval?(question)
+      return stop_command(session_id, question, via: via) if continue?(question) && !may_continue?(question)
+      return answer_command(session_id, question, "Continue", via: via) if continue?(question)
 
       # The one option a parent may pick (cost-cap's Stop under hard).
       only = Array(question[:allowed_options])
-      return "chi answer #{session_id} --question #{question[:id]} --option #{option_arg(only.first)}" if only.size == 1
+      return answer_command(session_id, question, option_arg(only.first), via: via) if only.size == 1
 
-      "chi answer #{session_id} --question #{question[:id]} --option N"
+      answer_command(session_id, question, "N", via: via)
+    end
+
+    # chi answer ID --question QID --option +option+ (its words after
+    # --option: a label, maybe --text).
+    def answer_command(session_id, question, option, via: ChiInvocation::HERE)
+      via.command("answer #{session_id} --question #{question[:id]} --option #{option}")
     end
 
     # What a parent does with an approval it may not allow.
@@ -239,17 +250,18 @@ module Samagotchi
       question.fetch(:allowed_options, question[:options]).include?(Guardrails::ParentPolicy::CONTINUE)
     end
 
-    def stop_command(session_id, question)
-      "chi answer #{session_id} --question #{question[:id]} --option Stop --text WHY"
+    def stop_command(session_id, question, via: ChiInvocation::HERE)
+      answer_command(session_id, question, "Stop --text WHY", via: via)
     end
 
     def option_arg(label) = label.match?(/\A[\w.-]+\z/) ? label : label.inspect
 
     # The other way: the user answers it in chi (the web's bell and badge
     # say it waits), and a wait with no message waits past it.
-    def leave_open(session_id)
-      "or leave it open: tell your user it waits in chi web (session #{session_id[0, 8]}); " \
-        "chi send --wait --format json #{session_id} waits until they answer"
+    def leave_open(session_id, via: ChiInvocation::HERE)
+      web = via.remote? ? via.web : "chi web"
+      "or leave it open: tell your user it waits in #{web} (session #{session_id[0, 8]}); " \
+        "#{via.command("send --wait --format json #{session_id}")} waits until they answer"
     end
 
     # @param question [PendingQuestion, Hash, nil] a pending question, or a
@@ -267,13 +279,13 @@ module Samagotchi
     end
 
     # What a message does to a step-limit question.
-    def message_drops(session_id)
-      "a message instead (chi send #{session_id} -m …) drops it and starts a new turn"
+    def message_drops(session_id, via: ChiInvocation::HERE)
+      "a message instead (#{via.command("send #{session_id} -m …")}) drops it and starts a new turn"
     end
 
     # What a wait that ended without an answer says, one line.
-    def detail(result, session_id:, timeout: nil, turn_id: nil, strategy: nil)
-      attach = "chi --attach #{session_id}"
+    def detail(result, session_id:, timeout: nil, turn_id: nil, strategy: nil, via: ChiInvocation::HERE)
+      shows = via.shows(session_id)
       case result.status
       when :waiting_for_answer
         q = question(result.question, strategy: strategy)
@@ -281,20 +293,20 @@ module Samagotchi
           "waiting for an approval: #{first_line(q[:text])}; #{approval_advice(q, strategy: strategy)}"
         elsif continue?(q) && !may_continue?(q)
           "waiting at the step limit: #{first_line(q[:text])}; a parent may only stop it here " \
-            "(#{policy(strategy).label}): #{stop_command(session_id, q)}, or tell your user it waits"
+            "(#{policy(strategy).label}): #{stop_command(session_id, q, via: via)}, or tell your user it waits"
         elsif continue?(q)
           "waiting at the step limit: #{first_line(q[:text])}; " \
-            "answer Continue or Stop: chi answer #{session_id} --question #{q[:id]} --option Continue"
+            "answer Continue or Stop: #{answer_command(session_id, q, "Continue", via: via)}"
         else
-          "waiting for an answer: #{first_line(q[:text])}; open it: #{attach} or the web"
+          "waiting for an answer: #{first_line(q[:text])}; open it: #{via.open_it(session_id)}"
         end
-      when :no_reply then "#{no_reply_line(result, session_id, strategy: strategy)}; #{attach} shows it"
-      when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
-      when :worker_gone then "the worker is gone; #{attach} shows what happened"
+      when :no_reply then "#{no_reply_line(result, session_id, strategy: strategy, via: via)}; #{shows} shows it"
+      when :error then "the worker failed: #{result.text}; #{shows} shows what happened"
+      when :worker_gone then "the worker is gone; #{shows} shows what happened"
       when :stopped then "the session was stopped (chi sessions stop)"
       else
-        wait_again = "chi send --wait --turn #{turn_id} #{session_id}" unless turn_id.to_s.empty?
-        hint = wait_again || attach
+        wait_again = via.command("send --wait --turn #{turn_id} #{session_id}") unless turn_id.to_s.empty?
+        hint = wait_again || shows
         timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
       end
     end
@@ -302,7 +314,7 @@ module Samagotchi
     # The whole question for stderr: header, text, numbered options, what
     # else it takes, and the commands that answer it.
     # @return [String] lines, newline-terminated
-    def question_text(pending, session_id:, strategy: nil)
+    def question_text(pending, session_id:, strategy: nil, via: ChiInvocation::HERE)
       q = question(pending, strategy: strategy)
       lines = ["waiting for an answer (#{q[:kind]}): #{q[:header] || first_line(q[:text])}"]
       text_lines = q[:text].strip.lines.map(&:rstrip)
@@ -315,31 +327,31 @@ module Samagotchi
           lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
         else
           lines << "  #{approval_advice(q, strategy: strategy)}"
-          allows.each { |label| lines << "  allow: chi answer #{session_id} --question #{q[:id]} --option #{option_arg(label)}" }
+          allows.each { |label| lines << "  allow: #{answer_command(session_id, q, option_arg(label), via: via)}" }
         end
-        lines << "  deny: #{answer_with(session_id, q)}"
-        lines << "  #{leave_open(session_id)}"
+        lines << "  deny: #{answer_with(session_id, q, via: via)}"
+        lines << "  #{leave_open(session_id, via: via)}"
       elsif continue?(q)
         lines << if may_continue?(q)
-                   "  continue: #{answer_with(session_id, q)}"
+                   "  continue: #{answer_with(session_id, q, via: via)}"
                  else
                    "  continuing it is up to your user (#{policy(strategy).label}): stop it, or tell your user it waits"
                  end
-        lines << "  stop: #{stop_command(session_id, q)} (the text is optional; the model reads it)"
-        lines << "  #{message_drops(session_id)}"
+        lines << "  stop: #{stop_command(session_id, q, via: via)} (the text is optional; the model reads it)"
+        lines << "  #{message_drops(session_id, via: via)}"
       else
         lines << "  more than one allowed: repeat --option" if q[:multi_select]
         lines << "  free text allowed: --text" if q[:allow_freeform]
         if q[:allowed_options]
           lines << "  a parent may pick #{q[:allowed_options].map { |o| option_arg(o) }.join(", ")}; the others are up to your user"
         end
-        lines << "  answer: #{answer_with(session_id, q)}"
-        lines << "  or open it: chi --attach #{session_id} or the web"
+        lines << "  answer: #{answer_with(session_id, q, via: via)}"
+        lines << "  or open it: #{via.open_it(session_id)}"
       end
       lines.map { |line| "#{line}\n" }.join
     end
 
-    def no_reply_line(result, session_id = nil, strategy: nil)
+    def no_reply_line(result, session_id = nil, strategy: nil, via: ChiInvocation::HERE)
       return command_line(result) if result.origin == TurnCheckpoint::COMMAND_ORIGIN
 
       case result.outcome
@@ -354,7 +366,7 @@ module Samagotchi
         ran_out = "the turn ran out of iterations#{" (#{result.limit} steps)" if result.limit} before it answered"
         strategy = policy(strategy)
         if strategy.allow?(Guardrails::ParentPolicy::SPEND)
-          "#{ran_out}; chi send #{session_id} -m '/continue yes' continues it, a message drops it"
+          "#{ran_out}; #{via.command("send #{session_id} -m '/continue yes'")} continues it, a message drops it"
         else
           # No /continue yes hint: a parent may not continue it here.
           "#{ran_out}; continuing it is up to your user (#{strategy.label}), a message drops it"

data/lib/samagotchi/remote_command.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "paths"
+require_relative "remotes"
+require_relative "session_access"
+require_relative "session_access/http_transport"
+require_relative "session_access/remote"
+
+module Samagotchi
+  # `chi remote`: the other machines whose sessions chi --remote NAME (or
+  # CHI_REMOTE=NAME) reaches through their chi web (Remotes,
+  # SessionAccess::Remote). add checks the address and the token with GET
+  # /api/info before it saves anything; ls never prints a token.
+  class RemoteCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi remote <add|ls|rm> [options]
+        add NAME URL [--token-file FILE | --token-stdin]
+              a machine's chi web (http://LAN-IP:PORT, as chi web prints it with web.host: lan;
+              port 4567 by default), with its access token (chi web's LAN link carries it, after
+              ?token=). It is checked first: the chi it runs, or why it can't be reached. Saved
+              in #{Paths.tilde(Remotes.path)} (0600); an existing NAME is replaced.
+        ls [--format json]    the remotes (never their tokens)
+        rm NAME               forget one
+      Then: chi --remote NAME send|answer|note|context|sessions …, or CHI_REMOTE=NAME.
+    TEXT
+
+    SUBCOMMANDS = %w[add ls rm].freeze
+
+    FLAGS = {
+      "add" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--token-file"
+        f.switch "--token-stdin"
+      end,
+      "ls" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--format" },
+      "rm" => CLI::Flags.new(help: HELP_WORDS)
+    }.freeze
+
+    # @param transport [#call, nil] (entry) → a transport for add's check;
+    #   HTTPTransport by default
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, path: Remotes.path, transport: nil)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @path = path
+      @transport = transport || ->(entry) { SessionAccess::HTTPTransport.new(entry) }
+    end
+
+    # @return [Integer] exit status: 0 done, 1 refused or unreachable, 2 usage
+    def run
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return 0
+      end
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      send(:"run_#{@sub}", parsed.options, parsed.args)
+    rescue Remotes::Invalid => e
+      error_line("#{command_name}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    private
+
+    def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi remote #{@sub}" : "chi remote"
+    def usage_on_error = nil
+
+    def run_add(options, args)
+      return usage_error("give NAME and URL") unless args.size == 2
+      return usage_error("--token-file and --token-stdin: choose one") if options[:token_file] && options[:token_stdin]
+
+      name, url = args
+      begin
+        Remotes.check_name!(name)
+        url = Remotes.normalize_url(url)
+      rescue Remotes::Invalid => e
+        return usage_error(e.message)
+      end
+      token = read_token(options)
+      return CLI::Exit::FAILED if token == false
+
+      entry = Remotes::Entry.new(name: name, url: url, token: token)
+      found = check(entry) or return CLI::Exit::FAILED
+      Remotes.put(entry, path: @path)
+      @stdout.puts("#{name}  #{url}  chi #{found["version"]}, #{lan_words(found, entry)}")
+      0
+    end
+
+    def run_ls(options, args)
+      return usage_error("ls takes no arguments") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+
+      entries = Remotes.all(path: @path)
+      if format == "json"
+        @stdout.puts(JSON.generate(entries.map { |e| { name: e.name, url: e.url, token: !e.token.nil? } }))
+      elsif entries.empty?
+        @stdout.puts("no remotes (chi remote add NAME URL --token-file FILE)")
+      else
+        width = entries.map { |e| e.name.length }.max
+        entries.each { |e| @stdout.puts("#{e.name.ljust(width)}  #{e.url}#{"  (no token)" unless e.token}") }
+      end
+      0
+    end
+
+    def run_rm(_options, args)
+      return usage_error("give one NAME") unless args.size == 1
+      raise Remotes::NotFound, args.first unless Remotes.remove(args.first, path: @path)
+
+      @stdout.puts("#{args.first}  removed")
+      0
+    end
+
+    # The token from its file or stdin; nil for none (a loopback chi web
+    # needs none), false after the error line.
+    def read_token(options)
+      text = if options[:token_file]
+               begin
+                 File.read(File.expand_path(options[:token_file]))
+               rescue SystemCallError => e
+                 error_line("#{command_name}: can't read #{options[:token_file]}: #{e.message.sub(/ @ .*/, "")}")
+                 return false
+               end
+             elsif options[:token_stdin]
+               read_stdin.to_s
+             end
+      return nil if text.nil?
+
+      token = text.strip
+      return token unless token.empty? || token.match?(/\s/)
+
+      error_line("#{command_name}: #{options[:token_file] || "stdin"} holds no token (one line, chi web's web-token file)")
+      false
+    end
+
+    # GET /api/info with the token: the answer, or nil after the line that
+    # says why it can't be used.
+    def check(entry)
+      reply = @transport.call(entry).call(:get, "/api/info")
+      problem = SessionAccess::Remote.info_problem(entry, reply)
+      return fail_line(problem.message) if problem
+
+      reply.json
+    rescue SessionAccess::RemoteFailed => e
+      fail_line("#{e.message}: start chi web on #{entry.host} with web.host: lan")
+    end
+
+    def lan_words(found, entry)
+      return "loopback only" unless found["lan"]
+
+      found["lan"] == entry.host ? "LAN #{found["lan"]}" : "LAN #{found["lan"]} (reached as #{entry.host})"
+    end
+
+    def fail_line(message)
+      error_line("#{command_name}: #{message}")
+      nil
+    end
+  end
+end

data/lib/samagotchi/remotes.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "uri"
+require "yaml"
+require "fileutils"
+require_relative "paths"
+require_relative "atomic_file"
+
+module Samagotchi
+  # chi's remotes: other machines' chi web, each by a name chi --remote NAME
+  # (or CHI_REMOTE=NAME) takes. They live in one file only you can read,
+  # $XDG_CONFIG_HOME/samagotchi/remotes.yml (0600), their access tokens
+  # inside (a token runs commands as you on that machine):
+  #
+  #   remotes:
+  #     studio:
+  #       url: http://192.168.1.29:4567
+  #       token: …
+  #
+  # chi remote add / ls / rm write and read it (RemoteCommand).
+  module Remotes
+    FILE = "remotes.yml"
+    # A name as git takes a remote's, short: letters, digits, - and _.
+    NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]{0,39}\z/
+
+    # One remote: its +name+, chi web's +url+ (scheme, host and port, no
+    # path) and its access +token+ (nil for a loopback chi web, which needs
+    # none). #inspect leaves the token out.
+    Entry = Data.define(:name, :url, :token) do
+      def host = URI(url).host
+
+      # How a failure names it: "remote studio (http://192.168.1.29:4567)".
+      def label = "remote #{name} (#{url})"
+
+      def inspect = "#<Samagotchi::Remotes::Entry name=#{name.inspect} url=#{url.inspect} token=[redacted]>"
+      alias_method :to_s, :inspect
+    end
+
+    # A name or URL chi remote can't take, or a remotes.yml it can't read:
+    # the message says which.
+    class Invalid < StandardError; end
+
+    # No remote by that name: the one message chi --remote, CHI_REMOTE and
+    # chi remote rm give.
+    class NotFound < Invalid
+      def initialize(name)
+        super("no remote #{name} (chi remote ls lists them; chi remote add NAME URL adds one)")
+      end
+    end
+
+    module_function
+
+    # @return [String] $XDG_CONFIG_HOME/samagotchi/remotes.yml
+    def path(env: ENV) = File.join(Paths.config_home(env: env), Paths::APP_DIR, FILE)
+
+    # @return [Array<Entry>] by name
+    # @raise [Invalid] a file that isn't remotes.yml's shape
+    def all(path: self.path)
+      raw = File.exist?(path) ? YAML.safe_load_file(path) : nil
+      remotes = raw.is_a?(Hash) ? raw["remotes"] : nil
+      return [] if raw.nil? || (raw.is_a?(Hash) && remotes.nil?)
+      raise Invalid, "#{Paths.tilde(path)}: remotes: is a map of names" unless remotes.is_a?(Hash)
+
+      remotes.map do |name, fields|
+        unless fields.is_a?(Hash) && fields["url"].is_a?(String)
+          raise Invalid, "#{Paths.tilde(path)}: remote #{name} has no url"
+        end
+
+        Entry.new(name: name.to_s, url: fields["url"], token: fields["token"]&.to_s)
+      end.sort_by(&:name)
+    rescue Psych::Exception => e
+      raise Invalid, "#{Paths.tilde(path)}: #{e.message}"
+    end
+
+    # @return [Entry]
+    # @raise [NotFound]
+    def find(name, path: self.path)
+      all(path: path).find { |entry| entry.name == name } or raise NotFound, name
+    end
+
+    # Saves +entry+, replacing one of its name.
+    def put(entry, path: self.path)
+      write(all(path: path).reject { |other| other.name == entry.name } + [entry], path)
+    end
+
+    # @return [Boolean] whether there was one
+    def remove(name, path: self.path)
+      entries = all(path: path)
+      kept = entries.reject { |entry| entry.name == name }
+      return false if kept.size == entries.size
+
+      write(kept, path)
+      true
+    end
+
+    # @raise [Invalid] unless +name+ is one
+    def check_name!(name)
+      return name if NAME.match?(name.to_s)
+
+      raise Invalid, "a remote's name is letters, digits, - and _ (up to 40), not #{name.inspect}"
+    end
+
+    # chi web's address as chi remote add takes it: http(s)://HOST:PORT,
+    # the port 4567 (chi web's default) when none is given, no path.
+    # @return [String]
+    # @raise [Invalid]
+    def normalize_url(text)
+      text = text.to_s.strip
+      text = "http://#{text}" unless text.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+      uri = URI.parse(text)
+      unless %w[http https].include?(uri.scheme&.downcase) && uri.host && !uri.host.empty?
+        raise Invalid, "give chi web's address, http://HOST:PORT, not #{text}"
+      end
+      raise Invalid, "give chi web's address alone, http://HOST:PORT, without a path or query" unless ["", "/"].include?(uri.path) && uri.query.nil?
+
+      port = uri.port == uri.default_port && !text.match?(%r{://[^/]+:\d+}) ? 4567 : uri.port
+      host = uri.host.include?(":") && !uri.host.start_with?("[") ? "[#{uri.host}]" : uri.host
+      "#{uri.scheme.downcase}://#{host.downcase}:#{port}"
+    rescue URI::InvalidURIError
+      raise Invalid, "give chi web's address, http://HOST:PORT, not #{text}"
+    end
+
+    def write(entries, path)
+      FileUtils.mkdir_p(File.dirname(path))
+      remotes = entries.sort_by(&:name).to_h { |entry| [entry.name, { "url" => entry.url, "token" => entry.token }.compact] }
+      AtomicFile.write(path, YAML.dump({ "remotes" => remotes }), perm: 0o600)
+    end
+    private_class_method :write
+  end
+end