rpremote 0.5.0 → 0.7.0

data/lib/rpremote/cli.rb

@@ -3,6 +3,7 @@
 require "optparse"
 require_relative "build_command"
 require_relative "bootsel_command"
+require_relative "cli/filesystem_commands"
 require_relative "config_show"
 require_relative "dfu_command"
 require_relative "deploy_command"
@@ -12,9 +13,10 @@ require_relative "mrbgems_command"
 require_relative "recursive_copy"
 require_relative "setup_command"
 
-# rubocop:disable Metrics/ClassLength
 module Rpremote
   class CLI
+    include FilesystemCommands
+
     def self.start(argv = ARGV, config: Config, **options)
       new(**options).run(argv, config: config)
     rescue OptionParser::ParseError, ArgumentError, SystemCallError, Rpremote::Error => e
@@ -136,44 +138,24 @@ module Rpremote
       ConfigShow.run(args, defaults: config_options, output: stdout)
     end
 
-    def fs(args)
-      subcommand = args.shift
-      recursive = subcommand == "cp" && (args.delete("--recursive") || args.delete("-r"))
-      options = parse_connection_options(args)
-      case subcommand
-      when "cp"
-        copy(args, options, recursive: recursive)
-      when "push"
-        copy(args, options, recursive: true, command: "push")
-      when "cat"
-        cat(args, options)
-      when "ls", "rm", "mkdir"
-        filesystem_shell_command(subcommand, args, options)
-      else
-        raise ArgumentError, "unknown fs command: #{subcommand || "(none)"}"
-      end
-    rescue Shell::TimeoutError => e
-      raise Shell::TimeoutError, "filesystem connection failed: #{e.message}"
-    end
-
     def run_file(args)
       reset_on_timeout = !args.delete("--reset-on-timeout").nil?
-      options = parse_connection_options(args)
+      options = parse_connection_options(args, mrbgems_lock: true)
       raise ArgumentError, "usage: rpremote run FILE [options]" unless args.length == 1
 
       source = args.first
       source = File.join(source, "main.rb") if File.directory?(source)
-      data = prepend_mrbgem_requires(File.binread(source))
+      data = prepend_mrbgem_requires(File.binread(source), options[:mrbgems_lock])
       execute_temporary(data, options, output: stdout, reset_on_timeout: reset_on_timeout)
     rescue Errno::ENOENT => e
       raise ArgumentError, e.message
     end
 
     def execute_code(args)
-      options = parse_connection_options(args)
+      options = parse_connection_options(args, mrbgems_lock: true)
       raise ArgumentError, "usage: rpremote exec CODE [options]" unless args.length == 1
 
-      execute_temporary(prepend_mrbgem_requires(args.first), options, output: stdout)
+      execute_temporary(prepend_mrbgem_requires(args.first, options[:mrbgems_lock]), options, output: stdout)
     end
 
     def execute_temporary(data, options, output: nil, reset_on_timeout: false)
@@ -197,8 +179,13 @@ module Rpremote
             "#{timeout_error.message}; automatic reset failed: #{e.message}"
     end
 
-    def prepend_mrbgem_requires(data)
-      Mrbgems.new(cwd: Dir.pwd).prepend_requires(data)
+    def prepend_mrbgem_requires(data, lock_file)
+      return data 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(cwd: Dir.pwd, lock_path: path).prepend_requires(data)
     end
 
     def interactive(args, repl: false)
@@ -227,18 +214,23 @@ module Rpremote
       stdout.puts("reset R2P2: #{port_path}")
     end
 
-    def parse_connection_options(args, default_timeout: PicoModem::DEFAULT_TIMEOUT)
+    def parse_connection_options(args, default_timeout: PicoModem::DEFAULT_TIMEOUT, mrbgems_lock: false)
       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)
       }
+      options[:mrbgems_lock] = config_options[:mrbgems_lock] if mrbgems_lock
       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 }
+        if mrbgems_lock
+          opts.on("--lockfile FILE") { |value| options[:mrbgems_lock] = value }
+          opts.on("--no-mrbgems") { options[:mrbgems_lock] = false }
+        end
       end
       parser.parse!(args)
       raise ArgumentError, "--baud must be positive" unless options[:baud].positive?
@@ -246,82 +238,5 @@ module Rpremote
 
       options
     end
-
-    def copy(args, options, recursive: false, command: "cp")
-      usage = command == "push" ? "rpremote fs push LOCAL_DIR :/REMOTE_DIR" : "rpremote fs cp SOURCE DESTINATION"
-      raise ArgumentError, "usage: #{usage} [options]" unless args.length == 2
-
-      source, destination = args
-      source_remote = RemotePath.remote?(source)
-      destination_remote = RemotePath.remote?(destination)
-      raise ArgumentError, "exactly one cp path must be remote (prefix remote paths with :)" if source_remote == destination_remote
-      return RecursiveCopy.new(output: stdout, serial: serial, device: device).call(source, destination, options) if recursive
-
-      ensure_filesystem_connection!(options)
-      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)
-      stdout.puts("deleting remote path permanently: #{path}") if command == "rm"
-      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 ensure_filesystem_connection!(options)
-      output = with_shell(options) { |shell| shell.execute("ls '/'") }
-      ensure_filesystem_success!("ls", output)
-    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
-# rubocop:enable Metrics/ClassLength

data/lib/rpremote/config.rb

@@ -16,17 +16,17 @@ module Rpremote
       baud: Integer,
       timeout: Numeric,
       language: String,
-      mrbgems: [String, FalseClass].freeze
+      mrbgems_lock: [String, FalseClass].freeze
     }.freeze
     COMMAND_OPTIONS = {
       "setup" => %i[cache language language_version],
-      "build" => %i[cache language language_version board firmware mrbgems],
+      "build" => %i[cache language language_version board firmware mrbgems_lock],
       "bootsel" => %i[mount port baud timeout],
-      "deploy" => %i[cache language language_version board firmware mrbgems mount port baud timeout],
+      "deploy" => %i[cache language language_version board firmware mrbgems_lock mount port baud timeout],
       "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],
+      "run" => %i[port baud timeout language mrbgems_lock],
+      "exec" => %i[port baud timeout language mrbgems_lock],
       "reset" => %i[port baud timeout],
       "monitor" => %i[port baud timeout],
       "repl" => %i[port baud timeout],
@@ -106,6 +106,7 @@ module Rpremote
         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?
 

data/lib/rpremote/config_show.rb

@@ -38,7 +38,7 @@ module Rpremote
         board: defaults.fetch(:board, Target::DEFAULT_BOARD),
         cache: 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),
@@ -53,8 +53,8 @@ module Rpremote
         opts.on("--board BOARD") { |value| options[:board] = value }
         opts.on("--cache DIR") { |value| options[:cache] = value }
         opts.on("--firmware FILE") { |value| options[:firmware] = value }
-        opts.on("--mrbgems FILE") { |value| options[:mrbgems] = value }
-        opts.on("--no-mrbgems") { options[:mrbgems] = false }
+        opts.on("--lockfile FILE") { |value| options[:mrbgems_lock] = value }
+        opts.on("--no-mrbgems") { options[:mrbgems_lock] = false }
         opts.on("--mount DIR") { |value| options[:mount] = value }
         opts.on("--port PORT") { |value| options[:port] = value }
         opts.on("--baud RATE", Integer) { |value| options[:baud] = value }
@@ -70,19 +70,27 @@ module Rpremote
         cache_dir: options[:cache],
         firmware: options[:firmware]
       )
+      print_target_options(target)
+      print_runtime_options(options)
+    end
+
+    def print_target_options(target)
       output.puts("language=#{target.language}")
       output.puts("language_version=#{target.language_version}")
       output.puts("board=#{target.board}")
       output.puts("cache=#{target.cache_dir}")
       output.puts("firmware=#{target.firmware_path}")
-      output.puts("mrbgems=#{mrbgems_value(options[:mrbgems])}")
+    end
+
+    def print_runtime_options(options)
+      output.puts("mrbgems_lock=#{mrbgems_lock_value(options[:mrbgems_lock])}")
       output.puts("mount=#{options[:mount] || "auto"}")
       output.puts("port=#{options[:port] || "auto"}")
       output.puts("baud=#{options[:baud]}")
       output.puts("timeout=#{options[:timeout]}")
     end
 
-    def mrbgems_value(value)
+    def mrbgems_lock_value(value)
       return "false" if value == false
 
       value || "auto"

data/lib/rpremote/deploy_command.rb

@@ -9,79 +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
 
-    # The command intentionally keeps the deployment stages visible in execution order.
-    # 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)
@@ -95,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
 
@@ -158,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),
@@ -176,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