rpremote 0.1.0

data/lib/rpremote/cli.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "build_command"
+require_relative "dfu_command"
+require_relative "flash_command"
+require_relative "help"
+require_relative "mrbgems_command"
+require_relative "setup_command"
+
+module Rpremote
+  class CLI
+    def self.start(argv = ARGV, config: Config, **options)
+      new(**options).run(argv, config: config)
+    rescue OptionParser::ParseError, ArgumentError, SystemCallError, Rpremote::Error => e
+      options.fetch(:stderr, $stderr).puts("rpremote: #{e.message}")
+      1
+    end
+
+    def initialize(
+      stdout: $stdout,
+      stderr: $stderr,
+      serial: Serial,
+      device: Device,
+      flasher: Flasher
+    )
+      @stdout = stdout
+      @stderr = stderr
+      @serial = serial
+      @device = device
+      @flasher = flasher
+    end
+
+    def run(argv, config: Config)
+      args = argv.dup
+      @config_class = config
+      @config_filename, config_required = config.extract_option!(args)
+      command = args.shift
+      @config_options = config.load_command(command, filename: config_filename, required: config_required)
+      dispatch(command, args)
+      0
+    end
+
+    private
+
+    attr_reader :stdout, :stderr, :serial, :device, :flasher,
+                :config_class, :config_filename, :config_options
+
+    def dispatch(command, args)
+      case command
+      when nil, "help", "--help", "-h"
+        stdout.puts(Help::TEXT)
+      when "--version", "-V"
+        stdout.puts(Rpremote::VERSION)
+      when "ports"
+        ports(args)
+      when "setup", "flash", "build", "dfu", "mrbgems"
+        project_command(command, args)
+      when "run", "monitor", "repl", "exec", "reset", "fs"
+        remote_command(command, args)
+      else
+        raise ArgumentError, "unknown command: #{command}"
+      end
+    end
+
+    def project_command(command, args)
+      case command
+      when "setup"
+        SetupCommand.run(
+          args,
+          defaults: config_options,
+          config: config_class,
+          config_filename: config_filename,
+          output: stdout
+        )
+      when "flash"
+        FlashCommand.run(args, defaults: config_options, output: stdout, flasher: flasher)
+      when "build"
+        BuildCommand.run(args, defaults: config_options, output: stdout, error: stderr)
+      when "dfu"
+        DfuCommand.run(
+          args, defaults: config_options, output: stdout, services: { serial: serial, device: device }
+        )
+      when "mrbgems"
+        MrbgemsCommand.run(args, output: stdout)
+      end
+    end
+
+    def remote_command(command, args)
+      case command
+      when "run" then run_file(args)
+      when "monitor" then interactive(args)
+      when "repl" then interactive(args, repl: true)
+      when "exec" then execute_code(args)
+      when "reset" then reset(args)
+      when "fs" then fs(args)
+      end
+    end
+
+    def ports(args)
+      raise ArgumentError, "ports does not accept arguments" unless args.empty?
+
+      found = device.ports
+      if found.empty?
+        stdout.puts("No R2P2 serial ports found.")
+      else
+        found.each { |path| stdout.puts(path) }
+      end
+    end
+
+    def fs(args)
+      subcommand = args.shift
+      options = parse_connection_options(args)
+      case subcommand
+      when "cp"
+        copy(args, options)
+      when "cat"
+        cat(args, options)
+      when "ls", "rm", "mkdir"
+        filesystem_shell_command(subcommand, args, options)
+      else
+        raise ArgumentError, "unknown fs command: #{subcommand || "(none)"}"
+      end
+    end
+
+    def run_file(args)
+      options = parse_connection_options(args)
+      raise ArgumentError, "usage: rpremote run FILE [options]" unless args.length == 1
+
+      source = args.first
+      data = File.binread(source)
+      stdout.write(execute_temporary(data, options))
+    rescue Errno::ENOENT => e
+      raise ArgumentError, e.message
+    end
+
+    def execute_code(args)
+      options = parse_connection_options(args)
+      raise ArgumentError, "usage: rpremote exec CODE [options]" unless args.length == 1
+
+      stdout.write(execute_temporary(args.first, options))
+    end
+
+    def execute_temporary(data, options)
+      Language.validate!(options[:language])
+      port_path = device.main_port(options[:port])
+      serial.open(port_path, baud: options[:baud]) do |port|
+        Runner.new(port, timeout: options[:timeout]).run(data)
+      end
+    end
+
+    def interactive(args, repl: false)
+      options = parse_connection_options(args)
+      command = repl ? "repl" : "monitor"
+      raise ArgumentError, "#{command} does not accept arguments" unless args.empty?
+
+      port_path = device.main_port(options[:port])
+      stderr.puts("connected: #{port_path} at #{options[:baud]} baud (Ctrl-] to exit)")
+      serial.open(port_path, baud: options[:baud]) do |port|
+        if repl
+          shell = Shell.new(port, timeout: options[:timeout])
+          shell.synchronize!
+          shell.send_command("irb")
+        end
+        Terminal.new(port, output: stdout).run(exit_sequence: repl ? "\x03\x04".b : nil)
+      end
+    end
+
+    def reset(args)
+      options = parse_connection_options(args, default_timeout: Resetter::DEFAULT_TIMEOUT)
+      raise ArgumentError, "reset does not accept arguments" unless args.empty?
+
+      port_path = device.main_port(options[:port])
+      Resetter.new(serial: serial, timeout: options[:timeout]).reset(port_path, baud: options[:baud])
+      stdout.puts("reset R2P2: #{port_path}")
+    end
+
+    def parse_connection_options(args, default_timeout: PicoModem::DEFAULT_TIMEOUT)
+      options = {
+        port: config_options[:port],
+        baud: config_options.fetch(:baud, Serial::BAUD_RATE),
+        timeout: config_options.fetch(:timeout, default_timeout),
+        language: config_options.fetch(:language, Target::DEFAULT_LANGUAGE)
+      }
+      parser = OptionParser.new do |opts|
+        opts.on("--port PORT") { |value| options[:port] = value }
+        opts.on("--baud RATE", Integer) { |value| options[:baud] = value }
+        opts.on("--timeout SECONDS", Float) { |value| options[:timeout] = value }
+        opts.on("--language LANGUAGE") { |value| options[:language] = value }
+      end
+      parser.parse!(args)
+      raise ArgumentError, "--baud must be positive" unless options[:baud].positive?
+      raise ArgumentError, "--timeout must be positive" unless options[:timeout].positive?
+
+      options
+    end
+
+    def copy(args, options)
+      raise ArgumentError, "usage: rpremote fs cp SOURCE DESTINATION [options]" unless args.length == 2
+
+      source, destination = args
+      source_remote = RemotePath.remote?(source)
+      destination_remote = RemotePath.remote?(destination)
+      if source_remote == destination_remote
+        raise ArgumentError, "exactly one cp path must be remote (prefix remote paths with :)"
+      end
+
+      if source_remote
+        data = with_modem(options) { |modem| modem.download(RemotePath.unwrap(source)) }
+        File.binwrite(local_destination(destination, source), data)
+        stdout.puts("downloaded #{data.bytesize} bytes: #{source} -> #{destination}")
+      else
+        data = File.binread(source)
+        with_modem(options) { |modem| modem.upload(RemotePath.unwrap(destination), data) }
+        stdout.puts("uploaded #{data.bytesize} bytes: #{source} -> #{destination}")
+      end
+    rescue Errno::ENOENT => e
+      raise ArgumentError, e.message
+    end
+
+    def cat(args, options)
+      raise ArgumentError, "usage: rpremote fs cat :/REMOTE/PATH [options]" unless args.length == 1
+      raise ArgumentError, "cat path must be remote (prefix it with :)" unless RemotePath.remote?(args.first)
+
+      stdout.write(with_modem(options) { |modem| modem.download(RemotePath.unwrap(args.first)) })
+    end
+
+    def filesystem_shell_command(command, args, options)
+      usage = "usage: rpremote fs #{command} :/REMOTE/PATH [options]"
+      raise ArgumentError, usage unless args.length == 1
+
+      path = RemotePath.validate(args.first)
+      output = with_shell(options) do |shell|
+        shell.execute("#{command} #{Shell.quote_argument(path)}")
+      end
+      ensure_filesystem_success!(command, output)
+      stdout.write(output)
+    end
+
+    def ensure_filesystem_success!(command, output)
+      failed = command == "ls" ? output.start_with?("ls:") : !output.empty?
+      raise Shell::CommandError, output.strip if failed
+    end
+
+    def with_modem(options)
+      port_path = device.main_port(options[:port])
+      serial.open(port_path, baud: options[:baud]) do |port|
+        yield PicoModem.new(port, timeout: options[:timeout])
+      end
+    end
+
+    def with_shell(options)
+      port_path = device.main_port(options[:port])
+      serial.open(port_path, baud: options[:baud]) do |port|
+        shell = Shell.new(port, timeout: options[:timeout])
+        shell.synchronize!
+        yield shell
+      end
+    end
+
+    def local_destination(destination, source)
+      return destination unless File.directory?(destination)
+
+      File.join(destination, File.basename(RemotePath.unwrap(source)))
+    end
+  end
+end

data/lib/rpremote/config.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Rpremote
+  class Config
+    DEFAULT_PATH = "config/setting.json"
+    OPTION_TYPES = {
+      port: String,
+      mount: String,
+      cache: String,
+      language_version: String,
+      board: String,
+      firmware: String,
+      baud: Integer,
+      timeout: Numeric,
+      language: String,
+      mrbgems: [String, FalseClass].freeze
+    }.freeze
+    COMMAND_OPTIONS = {
+      "setup" => %i[cache language language_version],
+      "build" => %i[cache language language_version board firmware mrbgems],
+      "dfu" => %i[cache language language_version port baud timeout],
+      "flash" => %i[cache language language_version board firmware mount port timeout],
+      "run" => %i[port baud timeout language],
+      "exec" => %i[port baud timeout language],
+      "reset" => %i[port baud timeout],
+      "monitor" => %i[port baud timeout],
+      "repl" => %i[port baud timeout],
+      "fs" => %i[port baud timeout],
+      "ports" => [],
+      "mrbgems" => []
+    }.freeze
+
+    Result = Data.define(:path, :created)
+
+    class Error < Rpremote::Error; end
+
+    def self.extract_option!(args)
+      filename = nil
+      index = 0
+      while index < args.length
+        argument = args[index]
+        break if argument == "--"
+
+        value, consumed = config_argument(args, index)
+        unless consumed
+          index += 1
+          next
+        end
+        raise Error, "--config specified more than once" if filename
+        raise Error, "--config requires a value" if value.nil? || value.empty?
+
+        filename = value
+        args.slice!(index, consumed)
+      end
+      [filename || DEFAULT_PATH, !filename.nil?]
+    end
+
+    def self.load_command(command, filename:, required:)
+      return {} if command.nil? || %w[help --help -h --version -V].include?(command)
+      return {} unless COMMAND_OPTIONS.key?(command)
+
+      load(command, filename: filename, required: required && command != "setup")
+    end
+
+    def self.load(command, filename: DEFAULT_PATH, required: false, cwd: Dir.pwd)
+      path = File.expand_path(filename, cwd)
+      text = File.read(path)
+      values = parse(text, path)
+      validate!(values)
+      values.slice(*COMMAND_OPTIONS.fetch(command, []))
+    rescue Errno::ENOENT
+      raise Error, "config file does not exist: #{path}" if required
+
+      {}
+    end
+
+    def self.setup(filename: DEFAULT_PATH, cwd: Dir.pwd)
+      path = File.expand_path(filename, cwd)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "wx") { |file| file.write("{}\n") }
+      Result.new(path: path, created: true)
+    rescue Errno::EEXIST
+      Result.new(path: path, created: false)
+    rescue SystemCallError => e
+      raise Error, "cannot create config file #{path}: #{e.message}"
+    end
+
+    def self.parse(text, path)
+      parsed = JSON.parse(text, symbolize_names: true)
+      raise Error, "config file must contain a JSON object: #{path}" unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError => e
+      raise Error, "invalid config file #{path}: #{e.message}"
+    end
+    private_class_method :parse
+
+    def self.validate!(values)
+      values.each do |key, value|
+        expected = OPTION_TYPES[key]
+        raise Error, "unknown config option: #{key}" unless expected
+        raise Error, "config option #{key} must be a #{type_name(expected)}" unless valid_value?(value, expected)
+        next unless %i[baud timeout].include?(key)
+        next if value.positive?
+
+        raise Error, "config option #{key} must be positive"
+      end
+    end
+    private_class_method :validate!
+
+    def self.valid_value?(value, expected)
+      types = Array(expected)
+      types.any? { |type| value.is_a?(type) } && (!value.is_a?(String) || !value.empty?)
+    end
+    private_class_method :valid_value?
+
+    def self.type_name(type)
+      return type.map { |item| type_name(item) }.join(" or ") if type.is_a?(Array)
+      return "false" if type == FalseClass
+
+      type == Numeric ? "number" : type.name.downcase
+    end
+    private_class_method :type_name
+
+    def self.config_argument(args, index)
+      argument = args[index]
+      return [args[index + 1], 2] if argument == "--config"
+      return [argument.delete_prefix("--config="), 1] if argument.start_with?("--config=")
+
+      [nil, nil]
+    end
+    private_class_method :config_argument
+  end
+end

data/lib/rpremote/device.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Rpremote
+  class Device
+    GLOBS = ["/dev/cu.usbmodem*", "/dev/tty.usbmodem*"].freeze
+
+    class NotFoundError < Rpremote::Error; end
+    class MultipleDevicesError < Rpremote::Error; end
+
+    class << self
+      def ports
+        GLOBS.flat_map { |pattern| Dir.glob(pattern) }.sort
+      end
+
+      def main_port(explicit_port = nil, available_ports: ports)
+        return validate_explicit_port(explicit_port) if explicit_port
+
+        callout_ports = available_ports.grep(%r{\A/dev/cu\.})
+        candidates = callout_ports.empty? ? available_ports : callout_ports
+        candidates = candidates.select { |path| cdc_zero?(path, candidates) }
+
+        case candidates.length
+        when 0
+          raise NotFoundError, "R2P2 serial port not found; connect the Pico 2 or use --port PORT"
+        when 1
+          candidates.first
+        else
+          raise MultipleDevicesError,
+                "multiple R2P2 devices found; use --port PORT (#{candidates.join(", ")})"
+        end
+      end
+
+      private
+
+      def validate_explicit_port(path)
+        raise NotFoundError, "serial port not found: #{path}" unless File.exist?(path)
+
+        path
+      end
+
+      # PicoRuby 3.4.x exposes two CDC interfaces and 4.x exposes three.
+      # macOS numbers the interfaces with trailing 1, 3, and (when present) 5.
+      # CDC 0 is therefore the first (trailing 1) interface in each USB group.
+      def cdc_zero?(path, available_ports)
+        basename = File.basename(path)
+        siblings = ports_for_group(path, available_ports)
+        siblings.length >= 2 && basename.end_with?("1")
+      end
+
+      def ports_for_group(path, available_ports)
+        prefix = path.sub(/[135]\z/, "")
+        available_ports.select { |candidate| candidate.sub(/[135]\z/, "") == prefix }
+      end
+    end
+  end
+end

data/lib/rpremote/dfu_command.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rpremote
+  class DfuCommand
+    DEFAULT_TIMEOUT = 10.0
+    TYPES = { ".rb" => "RUBY", ".mrb" => "RITE" }.freeze
+
+    def self.run(args, defaults:, output: $stdout, services: {})
+      default_services = { serial: Serial, device: Device, modem: PicoModem, runner: Runner, compiler: DfuCompiler }
+      services = default_services.merge(services)
+      subcommand = args.shift
+      case subcommand
+      when "app" then stage(args, defaults, output, services)
+      when "compile" then compile(args, defaults, output, services[:compiler])
+      when "status" then status(args, defaults, output, services)
+      else
+        raise ArgumentError,
+              "usage: rpremote dfu app FILE [options], dfu compile FILE [options], or dfu status [options]"
+      end
+    end
+
+    def self.stage(args, defaults, output, services)
+      options = parse_app_options(args, defaults)
+      raise ArgumentError, "usage: rpremote dfu app FILE [options]" unless args.length == 1
+
+      source = args.first
+      data = read_source(source)
+      type = options[:type] || type_for(source)
+      port_path = services[:device].main_port(options[:port])
+      verify_rite_version!(data, port_path, options, services) if type == "RITE"
+      services[:serial].open(port_path, baud: options[:baud]) do |port|
+        services[:modem].new(port, timeout: options[:timeout]).dfu(data, type: type)
+      end
+      output.puts("staged DFU #{type.downcase} app (#{data.bytesize} bytes): #{source}")
+      output.puts("restart R2P2 to activate it; the app must call DFU.confirm after a successful boot")
+    end
+    private_class_method :stage
+
+    def self.compile(args, defaults, output, compiler)
+      options = parse_compile_options(args, defaults)
+      raise ArgumentError, "usage: rpremote dfu compile FILE [options]" unless args.length == 1
+
+      target = Target.new(
+        language: options[:language], language_version: options[:language_version], cache_dir: options[:cache]
+      )
+      compiler.compile(args.first, target: target, destination: options[:output], output: output)
+    end
+    private_class_method :compile
+
+    def self.status(args, defaults, output, services)
+      options = parse_app_options(args, defaults)
+      raise ArgumentError, "usage: rpremote dfu status [options]" unless args.empty?
+
+      port_path = services[:device].main_port(options[:port])
+      code = <<~'RUBY'
+        require "dfu"
+        status = DFU.status
+        puts "active_slot=#{status["active_slot"]}"
+        puts "try_slot=#{status["try_slot"]}"
+        puts "boot_count=#{status["boot_count"]}/#{status["max_boot_attempts"]}"
+        %w[a b].each { |slot| item = status["slot_#{slot}"]; puts "slot_#{slot}=#{item["state"]} #{item["ext"] || "-"}" }
+      RUBY
+      result = services[:serial].open(port_path, baud: options[:baud]) do |port|
+        services[:runner].new(port, timeout: options[:timeout]).run(code)
+      end
+      output.write(result)
+    end
+    private_class_method :status
+
+    def self.parse_app_options(args, defaults)
+      options = {
+        port: defaults[:port],
+        baud: defaults.fetch(:baud, Serial::BAUD_RATE),
+        timeout: defaults.fetch(:timeout, DEFAULT_TIMEOUT),
+        type: nil
+      }
+      OptionParser.new do |parser|
+        parser.on("--type TYPE", %w[ruby rite]) { |value| options[:type] = value.upcase }
+        parser.on("--port PORT") { |value| options[:port] = value }
+        parser.on("--baud RATE", Integer) { |value| options[:baud] = value }
+        parser.on("--timeout SECONDS", Float) { |value| options[:timeout] = value }
+      end.parse!(args)
+      raise ArgumentError, "--baud must be positive" unless options[:baud].positive?
+      raise ArgumentError, "--timeout must be positive" unless options[:timeout].positive?
+
+      options
+    end
+    private_class_method :parse_app_options
+
+    def self.parse_compile_options(args, defaults)
+      options = {
+        language: defaults.fetch(:language, Target::DEFAULT_LANGUAGE),
+        language_version: defaults.fetch(:language_version, Target::DEFAULT_LANGUAGE_VERSION),
+        cache: defaults.fetch(:cache, Target::DEFAULT_CACHE_DIR),
+        output: nil
+      }
+      OptionParser.new do |parser|
+        parser.on("--output FILE") { |value| options[:output] = value }
+        parser.on("--language LANGUAGE") { |value| options[:language] = value }
+        parser.on("--language-version VERSION") { |value| options[:language_version] = value }
+        parser.on("--cache DIR") { |value| options[:cache] = value }
+      end.parse!(args)
+      options
+    end
+    private_class_method :parse_compile_options
+
+    def self.type_for(path)
+      TYPES.fetch(File.extname(path).downcase) do
+        raise ArgumentError, "cannot infer DFU type from #{path}; use --type ruby or --type rite"
+      end
+    end
+    private_class_method :type_for
+
+    def self.read_source(source)
+      File.binread(source)
+    rescue Errno::ENOENT
+      raise ArgumentError, "DFU app file not found: #{source} (current directory: #{Dir.pwd})"
+    end
+    private_class_method :read_source
+
+    def self.verify_rite_version!(data, port_path, options, services)
+      bytecode_version = data.byteslice(0, 8)
+      unless bytecode_version&.match?(/\ARITE\d{4}\z/)
+        raise ArgumentError, "DFU RITE app must start with a RITE bytecode header"
+      end
+
+      picoruby_version = services[:serial].open(port_path, baud: options[:baud]) do |port|
+        services[:runner].new(port, timeout: options[:timeout]).run("p PICORUBY_VERSION")[/\d+\.\d+\.\d+/]
+      end
+      unless picoruby_version
+        raise Rpremote::Error,
+              "connected R2P2 did not report PICORUBY_VERSION; use a .rb app or update R2P2"
+      end
+      device_version = rite_version_for(picoruby_version)
+      return if bytecode_version == device_version
+
+      raise Rpremote::Error,
+            "RITE bytecode version #{bytecode_version} does not match connected R2P2 #{device_version}; " \
+            "compile with rpremote dfu compile using the installed PicoRuby version"
+    end
+    private_class_method :verify_rite_version!
+
+    def self.rite_version_for(picoruby_version)
+      case picoruby_version.split(".").first
+      when "3" then "RITE0300"
+      when "4" then "RITE0400"
+      else
+        raise Rpremote::Error, "unsupported connected PicoRuby version: #{picoruby_version}"
+      end
+    end
+    private_class_method :rite_version_for
+  end
+end

data/lib/rpremote/dfu_compiler.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rpremote
+  class DfuCompiler
+    class Error < Rpremote::Error; end
+
+    def self.compile(source, target:, destination: nil, output: $stdout, runner: nil)
+      raise Error, "DFU bytecode compilation currently supports only picoruby" unless target.language == "picoruby"
+      raise ArgumentError, "DFU source must have a .rb extension" unless File.extname(source).downcase == ".rb"
+
+      source = File.expand_path(source)
+      raise ArgumentError, "DFU source file not found: #{source}" unless File.file?(source)
+
+      compiler = find_compiler(target.source_dir)
+      destination ||= source.sub(/\.rb\z/i, ".mrb")
+      destination = File.expand_path(destination)
+      FileUtils.mkdir_p(File.dirname(destination))
+      success = (runner || method(:run)).call(compiler, "-o", destination, source)
+      raise Error, "PicoRuby compiler failed: #{compiler}" unless success
+
+      rite_version = rite_version(File.binread(destination, 8))
+      output.puts("compiled #{rite_version} app: #{source} -> #{destination}")
+      destination
+    end
+
+    def self.find_compiler(source_dir)
+      %w[picorbc mrbc].each do |name|
+        path = File.join(source_dir, "build/host/bin", name)
+        return path if File.executable?(path)
+      end
+      raise Error, "PicoRuby compiler is not built in #{source_dir}; build the selected PicoRuby source first"
+    end
+    private_class_method :find_compiler
+
+    def self.run(*command)
+      system(*command)
+    end
+    private_class_method :run
+
+    def self.rite_version(data)
+      version = data.b.byteslice(0, 8)
+      return version if version&.match?(/\ARITE\d{4}\z/)
+
+      raise Error, "PicoRuby compiler did not produce a RITE bytecode file"
+    end
+    private_class_method :rite_version
+  end
+end