rpremote 0.6.0 → 0.7.0

data/lib/rpremote/deploy_command.rb

@@ -9,78 +9,106 @@ module Rpremote
     SHELL_READY_TIMEOUT = 2.0
     RETRY_INTERVAL = 0.25
 
+    Context = Data.define(:options, :output, :error, :services, :target_options, :firmware_path)
+
     class Error < Rpremote::Error; end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def self.run(args, defaults:, output: $stdout, error: $stderr, services: {})
       options = parse_options(args, defaults)
       raise ArgumentError, "usage: rpremote deploy PATH [options]" unless args.length == 1
 
-      project = File.expand_path(args.first)
-      library, remote_library, source = project_files(project)
+      library, remote_library, source = project_files(File.expand_path(args.first))
       Language.validate!(options[:language])
+      context = deployment_context(options, output, error, services)
+      build_firmware(context)
+      result = flash_firmware(context)
+      connect_to_shell(context, result)
+      push_library(context, result, library, remote_library)
+      run_source(context, result, source)
+    rescue Errno::ENOENT => e
+      raise ArgumentError, e.message
+    end
 
-      flasher = services.fetch(:flasher, Flasher)
-      serial = services.fetch(:serial, Serial)
-      device = services.fetch(:device, Device)
-      runner = services.fetch(:runner, Runner)
+    def self.deployment_context(options, output, error, services)
       target_options = options.slice(:language, :language_version, :board, :cache_dir, :firmware)
       firmware_path = Target.new(**target_options).firmware_path(root: Dir.pwd)
+      Context.new(options:, output:, error:, services:, target_options:, firmware_path:)
+    end
+    private_class_method :deployment_context
+
+    def self.build_firmware(context)
+      return unless context.options[:build]
+
+      builder = context.services.fetch(:builder) { Builder.new }
+      context.output.puts("deploy build: #{context.firmware_path}")
+      builder.build(
+        **context.target_options,
+        mrbgems_lock: context.options[:mrbgems_lock],
+        output: context.output,
+        error: context.error
+      )
+    end
+    private_class_method :build_firmware
 
-      if options[:build]
-        builder = services.fetch(:builder) { Builder.new }
-        output.puts("deploy build: #{firmware_path}")
-        builder.build(
-          **target_options,
-          mrbgems: options[:mrbgems],
-          output: output,
-          error: error
-        )
-      end
-
-      flash_service = flasher.new(timeout: options[:timeout])
-      bootsel_mount = resolve_bootsel_mount(options, flash_service, output, services)
-
+    def self.flash_firmware(context)
+      options = context.options
+      flash_service = context.services.fetch(:flasher, Flasher).new(timeout: options[:timeout])
+      bootsel_mount = resolve_bootsel_mount(options, flash_service, context.output, context.services)
       mount = options[:mount] || "an automatically detected RP2350 BOOTSEL volume"
-      output.puts("deploy flash: #{firmware_path} to #{mount}; this replaces persistent board firmware")
-      result = flash_service.flash(
-        firmware_path,
-        mount: bootsel_mount,
-        port: options[:port]
+      context.output.puts(
+        "deploy flash: #{context.firmware_path} to #{mount}; this replaces persistent board firmware"
       )
+      flash_service.flash(context.firmware_path, mount: bootsel_mount, port: options[:port])
+    end
+    private_class_method :flash_firmware
 
-      connection_options = options.except(:build).merge(port: result.port)
-      output.puts("deploy connect: waiting for R2P2 Shell on #{result.port}")
+    def self.connect_to_shell(context, result)
+      options = context.options
+      context.output.puts("deploy connect: waiting for R2P2 Shell on #{result.port}")
       wait_for_shell(
-        port: result.port, baud: options[:baud], timeout: options[:timeout], serial: serial,
-        shell: services.fetch(:shell, Shell),
-        sleeper: services.fetch(:sleeper) { ->(seconds) { sleep(seconds) } },
-        clock: services.fetch(:clock) { -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) } }
+        port: result.port, baud: options[:baud], timeout: options[:timeout],
+        serial: context.services.fetch(:serial, Serial),
+        shell: context.services.fetch(:shell, Shell),
+        sleeper: context.services.fetch(:sleeper) { ->(seconds) { sleep(seconds) } },
+        clock: context.services.fetch(:clock) { -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) } }
       )
-      output.puts("deploy connect: ready on #{result.port}")
+      context.output.puts("deploy connect: ready on #{result.port}")
+    end
+    private_class_method :connect_to_shell
 
-      if File.directory?(library)
-        output.puts("deploy push: #{library} -> :#{remote_library}")
-        recursive_copy = services.fetch(:recursive_copy) do
-          RecursiveCopy.new(output: output, serial: serial, device: device)
-        end
-        recursive_copy.call(library, ":#{remote_library}", connection_options)
-      else
-        output.puts("deploy push: skipped; directory not found: #{library}")
+    def self.push_library(context, result, library, remote_library)
+      unless File.directory?(library)
+        context.output.puts("deploy push: skipped; directory not found: #{library}")
+        return
       end
 
-      output.puts("deploy run: #{source} on #{result.port}")
-      source_data = prepend_mrbgem_requires(File.binread(source), options[:mrbgems])
+      context.output.puts("deploy push: #{library} -> :#{remote_library}")
+      recursive_copy = context.services.fetch(:recursive_copy) do
+        RecursiveCopy.new(
+          output: context.output,
+          serial: context.services.fetch(:serial, Serial),
+          device: context.services.fetch(:device, Device)
+        )
+      end
+      connection_options = context.options.except(:build).merge(port: result.port)
+      recursive_copy.call(library, ":#{remote_library}", connection_options)
+    end
+    private_class_method :push_library
+
+    def self.run_source(context, result, source)
+      options = context.options
+      context.output.puts("deploy run: #{source} on #{result.port}")
+      source_data = prepend_mrbgem_requires(File.binread(source), options[:mrbgems_lock])
+      serial = context.services.fetch(:serial, Serial)
+      runner = context.services.fetch(:runner, Runner)
       run_output = serial.open(result.port, baud: options[:baud]) do |port|
         runner.new(port, timeout: options[:timeout]).run(
-          source_data, output: output, cleanup: false, remote_path: Runner::DEPLOY_REMOTE_PATH
+          source_data, output: context.output, cleanup: false, remote_path: Runner::DEPLOY_REMOTE_PATH
         )
       end
-      output.puts("deploy run: completed; output bytes: #{run_output.to_s.bytesize}")
-    rescue Errno::ENOENT => e
-      raise ArgumentError, e.message
+      context.output.puts("deploy run: completed; output bytes: #{run_output.to_s.bytesize}")
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    private_class_method :run_source
 
     def self.project_files(project)
       raise ArgumentError, "project directory not found: #{project}" unless File.directory?(project)
@@ -94,10 +122,13 @@ module Rpremote
     end
     private_class_method :project_files
 
-    def self.prepend_mrbgem_requires(source, definition)
-      return source if definition == false
+    def self.prepend_mrbgem_requires(source, lock_file)
+      return source if lock_file == false
+
+      path = lock_file || Mrbgems::DEFAULT_LOCK_PATH
+      raise ArgumentError, "mrbgems lock file does not exist: #{path}" if lock_file && !File.file?(path)
 
-      Mrbgems.new(path: definition || Mrbgems::DEFAULT_PATH, cwd: Dir.pwd).prepend_requires(source)
+      Mrbgems.new(lock_path: path, cwd: Dir.pwd).prepend_requires(source)
     end
     private_class_method :prepend_mrbgem_requires
 
@@ -157,7 +188,7 @@ module Rpremote
         board: defaults.fetch(:board, Target::DEFAULT_BOARD),
         cache_dir: defaults.fetch(:cache, Target::DEFAULT_CACHE_DIR),
         firmware: defaults[:firmware],
-        mrbgems: defaults[:mrbgems],
+        mrbgems_lock: defaults[:mrbgems_lock],
         mount: defaults[:mount],
         port: defaults[:port],
         baud: defaults.fetch(:baud, Serial::BAUD_RATE),
@@ -175,8 +206,8 @@ module Rpremote
         parser.on("--board BOARD") { |value| options[:board] = value }
         parser.on("--cache DIR") { |value| options[:cache_dir] = value }
         parser.on("--firmware FILE") { |value| options[:firmware] = value }
-        parser.on("--mrbgems FILE") { |value| options[:mrbgems] = value }
-        parser.on("--no-mrbgems") { options[:mrbgems] = false }
+        parser.on("--lockfile FILE") { |value| options[:mrbgems_lock] = value }
+        parser.on("--no-mrbgems") { options[:mrbgems_lock] = false }
         parser.on("--mount DIR") { |value| options[:mount] = value }
         parser.on("--port PORT") { |value| options[:port] = value }
         parser.on("--baud RATE", Integer) { |value| options[:baud] = value }

data/lib/rpremote/help/dfu_commands.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Help
+    def self.dfu_text(subcommand)
+      return dfu_app_text if subcommand == "app"
+      return dfu_compile_text if subcommand == "compile"
+      return dfu_status_text if subcommand == "status"
+      return dfu_remove_text if subcommand == "remove"
+
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:dfu_app)}
+               #{COMMAND_USAGE.fetch(:dfu_compile)}
+               #{COMMAND_USAGE.fetch(:dfu_status)}
+               #{COMMAND_USAGE.fetch(:dfu_remove)}
+
+        Stages and inspects PicoModem DFU applications. Run `rpremote dfu SUBCOMMAND --help` for details.
+      HELP
+    end
+
+    def self.dfu_app_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:dfu_app)}
+
+        Transfers a Ruby source or matching RITE bytecode application to the inactive DFU slot. The next R2P2 restart tries it.
+        Options default to the configured or automatically selected CDC 0 port, 115200 baud, and 20 seconds.
+        The transfer changes the staged boot application; use `rpremote reset` to restart and require DFU.confirm after a successful boot.
+      HELP
+    end
+
+    def self.dfu_compile_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:dfu_compile)}
+
+        Compiles Ruby source to bytecode that matches the selected PicoRuby version. The output defaults beside FILE.
+        It requires prepared PicoRuby source and does not connect to a board.
+      HELP
+    end
+
+    def self.dfu_status_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:dfu_status)}
+
+        Prints the active and candidate DFU A/B slots. Defaults are the configured or automatically selected CDC 0 port,
+        115200 baud, and 20 seconds. This command reads board state without changing it.
+      HELP
+    end
+
+    def self.dfu_remove_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:dfu_remove)}
+
+        Permanently removes the Ruby source and bytecode applications from both DFU A/B slots and resets their metadata.
+        Run `rpremote reset` afterward to stop the application already running in RAM. It does not remove /home/app.rb,
+        /home/app.mrb, other files, embedded mrbgems, or R2P2 firmware.
+      HELP
+    end
+  end
+end

data/lib/rpremote/help/filesystem_commands.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Help
+    def self.fs_text(subcommand)
+      return fs_subcommand_text(subcommand) if %w[cp push cat ls rm mkdir].include?(subcommand)
+
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:fs_cp)}
+               #{COMMAND_USAGE.fetch(:fs_push)}
+               #{COMMAND_USAGE.fetch(:fs_cat)}
+               #{COMMAND_USAGE.fetch(:fs_ls)}
+               #{COMMAND_USAGE.fetch(:fs_rm)}
+               #{COMMAND_USAGE.fetch(:fs_mkdir)}
+
+        Uses :/REMOTE/PATH for R2P2 paths. Run `rpremote fs SUBCOMMAND --help` for details.
+      HELP
+    end
+
+    def self.fs_subcommand_text(subcommand)
+      usage = COMMAND_USAGE.fetch(:"fs_#{subcommand}")
+      effect = case subcommand
+               when "rm" then "Deletes the remote path permanently."
+               when "mkdir" then "Creates a remote directory."
+               when "cp" then "Transfers one file, or recursively uploads a local directory with --recursive."
+               when "push" then "Creates missing remote directories and recursively uploads a local directory."
+               else "Reads remote files."
+               end
+      <<~HELP
+        Usage: #{usage}
+
+        #{effect} Defaults are the automatic CDC 0 port, 115200 baud, and 20 seconds.
+      HELP
+    end
+  end
+end

data/lib/rpremote/help/project_commands.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Help
+    def self.setup_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:setup)}
+
+        Creates config/setting.json when it does not exist, then downloads and prepares PicoRuby source and the official Raspberry Pi nuke_universal.uf2 firmware.
+        Options: --language LANGUAGE (picoruby), --language-version VERSION (latest), --cache DIR (firmware), --force.
+        This changes the project configuration and source cache but does not connect to a board.
+      HELP
+    end
+
+    def self.build_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:build)}
+
+        Builds a custom UF2 for the selected target. It writes generated files under build/ and the selected firmware path.
+        Options: --language LANGUAGE, --language-version VERSION, --board BOARD (pico2), --cache DIR (firmware),
+        --firmware FILE, --lockfile FILE, --no-mrbgems. A project Mrbgems.lock file is used automatically by default.
+      HELP
+    end
+
+    def self.build_clean_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:build_clean)}
+
+        Removes only the project's generated build/ directory. It does not remove firmware/, Mrbgems, or Mrbgems.lock.
+      HELP
+    end
+
+    def self.deploy_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:deploy)}
+
+        Enters BOOTSEL when needed, flashes the existing selected UF2, and waits for the R2P2 Shell to become ready.
+        With --build, builds the selected custom UF2 before entering BOOTSEL and flashing it.
+        If PATH/lib/NAME exists, it copies it to :/lib/NAME, where NAME is the final component of PATH. It then runs PATH/main.rb and preserves its Shell job, so hardware output remains active until the next command.
+        The stages run in order and stop at the first failure. Flashing replaces persistent board firmware.
+        deploy requires current PicoRuby 4.x firmware.
+        Options combine build, BOOTSEL, flash, library-copy, and run settings. The first install of firmware with automatic BOOTSEL still requires holding BOOTSEL.
+      HELP
+    end
+
+    def self.bootsel_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:bootsel)}
+
+        Asks the running R2P2 firmware to restart as an RP2350 BOOTSEL USB volume, then waits for that volume to appear.
+        By default it does not write firmware. This requires firmware built by a current rpremote; use physical BOOTSEL once to install it first.
+        --reset-flash-memory copies the official Raspberry Pi nuke_universal.uf2 in BOOTSEL mode and erases all external flash memory.
+        After resetting flash memory, wait for BOOTSEL to reappear and run `rpremote flash` to install R2P2 again.
+      HELP
+    end
+
+    def self.mrbgems_text(subcommand)
+      action = subcommand || "check|list|lock|update"
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:mrbgems).sub("SUBCOMMAND", action)}
+
+        Checks or lists build dependencies, writes a reproducible lock file, or updates locked GitHub commits.
+        `lock --with production --without test` includes common and production gems. Exclusions take precedence.
+        `update` resolves new commits using the same group options.
+      HELP
+    end
+
+    def self.flash_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:flash)}
+
+        Copies the selected UF2 to an RP2350 BOOTSEL volume and waits for R2P2 to reconnect. It replaces persistent board firmware.
+        Defaults select pico2, firmware/picoruby-latest-pico2.uf2, an automatic BOOTSEL mount and CDC 0 port, and 20 seconds.
+      HELP
+    end
+
+    def self.config_text(subcommand)
+      unless subcommand == "show"
+        return "Usage: #{COMMAND_USAGE.fetch(:config_show)}\n\nUse `rpremote config show --help` for the supported overrides.\n"
+      end
+
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:config_show)}
+
+        Prints the configuration file, defaults, and command-line overrides after resolution. It does not connect to a board or change state.
+      HELP
+    end
+  end
+end

data/lib/rpremote/help/remote_commands.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Help
+    def self.ports_text
+      "Usage: #{COMMAND_USAGE.fetch(:ports)}\n\nPrints each detected R2P2 CDC 0 serial path, one per line. It does not connect to a board.\n"
+    end
+
+    def self.run_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:run)}
+
+        Uploads FILE to R2P2, or main.rb when FILE is a directory, relays output, then removes the temporary remote file. Defaults are the automatic CDC 0 port,
+        115200 baud, a 20-second idle timeout, and picoruby. Output from the running program resets the idle timeout.
+        It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
+        --reset-on-timeout resets R2P2 after the run times out and the serial connection has closed.
+      HELP
+    end
+
+    def self.exec_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:exec)}
+
+        Runs short Ruby CODE through a temporary remote file, then removes it. Defaults are the automatic CDC 0 port,
+        115200 baud, a 20-second idle timeout, and picoruby. Output from the running program resets the idle timeout.
+        It exits nonzero when compatible R2P2 firmware reports a Ruby exception.
+      HELP
+    end
+
+    def self.monitor_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:monitor)}
+
+        Opens a serial monitor for the selected CDC 0 port. Defaults are 115200 baud and 20 seconds; exit with Ctrl-].
+      HELP
+    end
+
+    def self.repl_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:repl)}
+
+        Opens PicoIRB on the selected CDC 0 port. Defaults are 115200 baud and 20 seconds; exit with Ctrl-].
+      HELP
+    end
+
+    def self.reset_text
+      <<~HELP
+        Usage: #{COMMAND_USAGE.fetch(:reset)}
+
+        Reboots R2P2 and waits for reconnection. Defaults are the automatic CDC 0 port, 115200 baud, and 20 seconds.
+      HELP
+    end
+  end
+end

data/lib/rpremote/help/root_text.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Help
+    TEXT = <<~HELP.freeze
+      rpremote - R2P2 remote control for Raspberry Pi Pico 2
+
+      Usage:
+        #{COMMAND_USAGE.fetch(:setup)}
+        #{COMMAND_USAGE.fetch(:build)}
+        #{COMMAND_USAGE.fetch(:build_clean)}
+        #{COMMAND_USAGE.fetch(:bootsel)}
+        #{COMMAND_USAGE.fetch(:deploy)}
+        #{COMMAND_USAGE.fetch(:dfu_app)}
+        #{COMMAND_USAGE.fetch(:dfu_compile)}
+        #{COMMAND_USAGE.fetch(:dfu_status)}
+        #{COMMAND_USAGE.fetch(:dfu_remove)}
+        #{COMMAND_USAGE.fetch(:mrbgems).sub("SUBCOMMAND", "check|list|lock|update")}
+        #{COMMAND_USAGE.fetch(:flash)}
+        #{COMMAND_USAGE.fetch(:config_show)}
+        #{COMMAND_USAGE.fetch(:ports)}
+        #{COMMAND_USAGE.fetch(:run)}
+        #{COMMAND_USAGE.fetch(:monitor)}
+        #{COMMAND_USAGE.fetch(:repl)}
+        #{COMMAND_USAGE.fetch(:exec)}
+        #{COMMAND_USAGE.fetch(:reset)}
+        #{COMMAND_USAGE.fetch(:fs_cp)}
+        #{COMMAND_USAGE.fetch(:fs_push)}
+        #{COMMAND_USAGE.fetch(:fs_cat)}
+        #{COMMAND_USAGE.fetch(:fs_ls)}
+        #{COMMAND_USAGE.fetch(:fs_rm)}
+        #{COMMAND_USAGE.fetch(:fs_mkdir)}
+
+      `rpremote build clean` removes only the project's generated `build/` directory.
+
+      Configuration:
+        config/setting.json  default project options
+
+      Options:
+        --force           download the PicoRuby source again during setup
+        --build           build the selected firmware before deploy flashes it
+        --language-version VERSION
+                          use a PicoRuby tag or latest (default: latest)
+        --cache DIR       use another project cache directory
+        --lockfile FILE   use an explicit Mrbgems.lock for build, deploy, run, or exec
+        --no-mrbgems      do not build or automatically require locked mrbgems
+        --with GROUPS     lock common mrbgems and the comma-separated groups
+        --without GROUPS  exclude the comma-separated groups from the lock
+        --board BOARD
+                          select pico2 or pico2_w (default: pico2)
+        --firmware FILE   build to, or deploy or flash from, this UF2 path
+        --language LANGUAGE
+                          select the remote language (default: picoruby)
+        --config FILE     use another configuration file
+        --mount DIR       use an explicit RP2350 BOOTSEL drive
+        --port PORT       use an explicit R2P2 CDC 0 device
+        --baud RATE       serial baud rate (default: 115200)
+        --timeout SEC     timeout in seconds (default: 20)
+        -h, --help        show this help
+        -V, --version     show the version
+    HELP
+  end
+end