rpremote 0.1.0

data/sig/rpremote.rbs

@@ -0,0 +1,404 @@
+module Rpremote
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  module Language
+    SUPPORTED: Array[String]
+
+    def self.validate!: (String language) -> String
+  end
+
+  class Target
+    DEFAULT_LANGUAGE: String
+    DEFAULT_LANGUAGE_VERSION: String
+    DEFAULT_BOARD: String
+    DEFAULT_CACHE_DIR: String
+    IDENTIFIER_PATTERN: Regexp
+
+    attr_reader language: String
+    attr_reader language_version: String
+    attr_reader board: String
+    attr_reader cache_dir: String
+
+    def initialize: (
+      ?language: String,
+      ?language_version: String,
+      ?board: String,
+      ?cache_dir: String,
+      ?firmware: String?
+    ) -> void
+    def source_dir: (?root: String) -> String
+    def firmware_path: (?root: String?) -> String
+  end
+
+  module Checksum
+    def self.crc16: (String data, ?Integer initial) -> Integer
+    def self.crc32: (String data, ?Integer initial) -> Integer
+  end
+
+  module RemotePath
+    PREFIX: String
+
+    def self.remote?: (String path) -> bool
+    def self.unwrap: (String path) -> String
+    def self.validate: (String path) -> String
+  end
+
+  class Config
+    DEFAULT_PATH: String
+    OPTION_TYPES: Hash[Symbol, untyped]
+    COMMAND_OPTIONS: Hash[String, Array[Symbol]]
+
+    class Result < Data
+      attr_reader path: String
+      attr_reader created: bool
+    end
+
+    class Error < Rpremote::Error
+    end
+
+    def self.load: (
+      String command,
+      ?filename: String,
+      ?required: bool,
+      ?cwd: String
+    ) -> Hash[Symbol, untyped]
+    def self.extract_option!: (Array[String] args) -> [String, bool]
+    def self.load_command: (String? command, filename: String, required: bool) -> Hash[Symbol, untyped]
+    def self.setup: (?filename: String, ?cwd: String) -> Result
+  end
+
+  class PicoModem
+    CHUNK_SIZE: Integer
+    DEFAULT_TIMEOUT: Float
+    DFU_START: Integer
+    DFU_ACK: Integer
+    DFU_MAGIC: String
+    DFU_VERSION: Integer
+    DFU_TYPES: Array[String]
+
+    class Error < Rpremote::Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class ProtocolError < Error
+    end
+
+    class ChecksumError < ProtocolError
+    end
+
+    class DeviceError < Error
+    end
+
+    attr_reader io: untyped
+    attr_reader timeout: Float
+
+    def initialize: (untyped io, ?timeout: Float) -> void
+    def upload: (String path, String data) -> Integer
+    def download: (String path) -> String
+    def dfu: (String data, type: String) -> Integer
+    def send_frame: (Integer command, ?String payload) -> Integer
+    def receive_frame: () -> [Integer, String]
+  end
+
+  class Device
+    class NotFoundError < Rpremote::Error
+    end
+
+    class MultipleDevicesError < Rpremote::Error
+    end
+
+    def self.ports: () -> Array[String]
+    def self.main_port: (?String? explicit_port, ?available_ports: Array[String]) -> String
+  end
+
+  class Serial
+    BAUD_RATE: Integer
+
+    class ConfigurationError < Rpremote::Error
+    end
+
+    def self.open: [T] (String path, ?baud: Integer) { (Serial) -> T } -> T
+                 | (String path, ?baud: Integer) -> Serial
+
+    attr_reader path: String
+    attr_reader baud: Integer
+    attr_reader io: File
+
+    def initialize: (String path, ?baud: Integer) -> void
+    def read_nonblock: (Integer length) -> String
+    def write: (String data) -> Integer
+    def flush: () -> untyped
+    def close: () -> untyped
+    def closed?: () -> bool
+    def to_io: () -> File
+  end
+
+  class LanguageSource
+    class Error < Rpremote::Error
+    end
+
+    class DownloadError < Error
+    end
+
+    class ExtractError < Error
+    end
+
+    attr_reader language: String
+    attr_reader version: String
+    attr_reader cache_dir: String
+
+    def initialize: (
+      ?language: String,
+      ?version: String,
+      ?cache_dir: String,
+      ?fetcher: untyped,
+      ?extractor: untyped,
+      ?preparer: untyped
+    ) -> void
+    def setup: (?force: bool) -> String
+    def archive_url: () -> String
+    def archive_path: () -> String
+    def source_dir: () -> String
+  end
+
+  class Builder
+    class Error < Rpremote::Error
+    end
+
+    def initialize: (?root: String, ?runner: untyped, ?mrbgems_class: untyped) -> void
+    def build: (
+      ?language: String,
+      ?language_version: String,
+      ?board: String,
+      ?cache_dir: String,
+      ?firmware: String?,
+      ?mrbgems: String | false | nil,
+      ?output: IO,
+      ?error: IO
+    ) -> void
+    def clean: (?output: IO) -> void
+  end
+
+  class Mrbgems
+    DEFAULT_PATH: String
+    DEFAULT_LOCK_PATH: String
+    LOCK_VERSION: Integer
+
+    class Error < Rpremote::Error
+    end
+
+    class DefinitionError < Error
+    end
+
+    class LockError < Error
+    end
+
+    class Dependency < Data
+      attr_reader type: Symbol
+      attr_reader source: String
+      attr_reader branch: String?
+      attr_reader commit: String?
+      attr_reader path: String?
+    end
+
+    class Overlay < Data
+      attr_reader path: String
+      attr_reader fingerprint: String
+    end
+
+    attr_reader path: String
+    attr_reader lock_path: String
+
+    def initialize: (
+      ?path: String,
+      ?lock_path: String?,
+      ?cwd: String,
+      ?resolver: untyped
+    ) -> void
+    def exist?: () -> bool
+    def dependencies: () -> Array[Dependency]
+    def vm: () -> Symbol?
+    def check: () -> Array[Dependency]
+    def lock: (?update: bool) -> Hash[String, untyped]
+    def read_lock: (?required: bool) -> Hash[String, untyped]?
+    def generate_overlay: (
+      base_config: String,
+      target: String,
+      directory: String,
+      ?update: bool
+    ) -> Overlay
+  end
+
+  class Shell
+    DEFAULT_TIMEOUT: Float
+    PROMPT_START: String
+    PROMPT_END: String
+    CURSOR_POSITION_QUERY: String
+    CURSOR_POSITION_RESPONSE: String
+
+    class Error < Rpremote::Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class ProtocolError < Error
+    end
+
+    class CommandError < Error
+    end
+
+    attr_reader io: untyped
+    attr_reader timeout: Float
+
+    def self.quote_argument: (String argument) -> String
+    def initialize: (untyped io, ?timeout: Float) -> void
+    def synchronize!: () -> nil
+    def send_command: (String command) -> nil
+    def execute: (String command) -> String
+  end
+
+  class Terminal
+    EXIT_BYTE: Integer
+    BUFFER_SIZE: Integer
+
+    attr_reader serial_io: untyped
+    attr_reader input: IO
+    attr_reader output: IO
+
+    def initialize: (
+      untyped serial_io,
+      ?input: IO,
+      ?output: IO,
+      ?selector: untyped
+    ) -> void
+    def run: (?exit_sequence: String?) -> nil
+  end
+
+  class Runner
+    REMOTE_DIRECTORY: String
+
+    attr_reader io: untyped
+    attr_reader timeout: Float
+
+    def initialize: (
+      untyped io,
+      ?timeout: Float,
+      ?modem_class: untyped,
+      ?shell_class: untyped,
+      ?path_factory: untyped
+    ) -> void
+    def run: (String data) -> String
+  end
+
+  class Resetter
+    DEFAULT_TIMEOUT: Float
+    RETRY_INTERVAL: Float
+    PROBE_TIMEOUT: Float
+
+    class TimeoutError < Rpremote::Error
+    end
+
+    def initialize: (
+      ?serial: untyped,
+      ?timeout: Numeric,
+      ?shell_class: untyped,
+      ?sleeper: untyped,
+      ?clock: untyped,
+      ?port_probe: untyped
+    ) -> void
+    def reset: (String port_path, ?baud: Integer) -> String
+  end
+
+  class Flasher
+    DEFAULT_VOLUMES_ROOT: String
+    DEFAULT_TIMEOUT: Float
+    INFO_FILE: String
+
+    class Result < Data
+      attr_reader mount: String
+      attr_reader destination: String
+      attr_reader port: String
+    end
+
+    class Error < Rpremote::Error
+    end
+
+    class MountNotFoundError < Error
+    end
+
+    class InvalidTargetError < Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    attr_reader volumes_root: String
+    attr_reader timeout: Float
+
+    def initialize: (
+      ?volumes_root: String,
+      ?timeout: Numeric,
+      ?mount_probe: untyped,
+      ?port_probe: untyped,
+      ?sleeper: untyped
+    ) -> void
+    def flash: (String uf2_path, ?mount: String?, ?port: String?) -> Result
+    def find_mount: (?String? explicit_mount) -> String
+  end
+
+  class DfuCommand
+    DEFAULT_TIMEOUT: Float
+    TYPES: Hash[String, String]
+
+    def self.run: (
+      Array[String] args,
+      defaults: Hash[Symbol, untyped],
+      ?output: IO,
+      ?serial: untyped,
+      ?device: untyped,
+      ?services: Hash[Symbol, untyped]
+    ) -> void
+  end
+
+  class DfuCompiler
+    class Error < Rpremote::Error
+    end
+
+    def self.compile: (String source, target: Target, ?destination: String?, ?output: IO, ?runner: untyped) -> String
+  end
+
+  class SetupCommand
+    def self.run: (
+      Array[String] args,
+      defaults: Hash[Symbol, untyped],
+      config: untyped,
+      config_filename: String,
+      ?output: IO
+    ) -> void
+  end
+
+  class BuildCommand
+    def self.run: (
+      Array[String] args,
+      defaults: Hash[Symbol, untyped],
+      ?output: IO,
+      ?error: IO,
+      ?builder: Builder
+    ) -> void
+  end
+
+  class FlashCommand
+    def self.run: (
+      Array[String] args,
+      defaults: Hash[Symbol, untyped],
+      ?output: IO,
+      ?flasher: untyped
+    ) -> void
+  end
+end

data/tasks/firmware_build.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+
+REPOSITORY_ROOT = File.expand_path(ENV.fetch("RPREMOTE_ROOT", File.expand_path("../..", __dir__)))
+DEFAULT_BOARD = "pico2"
+SUPPORTED_BOARDS = %w[pico2 pico2_w].freeze
+
+def command!(*command, chdir:, env: {})
+  prefix = env.map { |key, value| "#{key}=#{value}" }.join(" ")
+  puts "+ #{prefix} #{command.join(" ")}".strip
+  abort "Command failed: #{command.join(" ")}" unless system(env, *command, chdir: chdir)
+end
+
+language = ENV.fetch("RPREMOTE_LANGUAGE", "picoruby")
+target_version = ENV.fetch("RPREMOTE_LANGUAGE_VERSION", "4.0.3")
+board = ENV.fetch("RPREMOTE_BOARD", DEFAULT_BOARD)
+abort "Unsupported language: #{language}" unless language == "picoruby"
+abort "Unsupported board: #{board}" unless SUPPORTED_BOARDS.include?(board)
+
+picoruby_root = File.expand_path(ENV.fetch("PICORUBY_DIR"))
+config_name = ENV.fetch("RPREMOTE_CONFIG_NAME", "r2p2-#{language}-#{board}")
+base_config_path = File.join(picoruby_root, "build_config", "#{config_name}.rb")
+config_path = ENV.fetch("RPREMOTE_MRUBY_CONFIG", base_config_path)
+fingerprint = ENV.fetch("RPREMOTE_MRBGEMS_FINGERPRINT", nil)
+build_name = [config_name, target_version, fingerprint].compact.join("-")
+r2p2_gem_dir = File.join(picoruby_root, "mrbgems/picoruby-r2p2")
+pico_sdk_path = File.join(r2p2_gem_dir, "lib/pico-sdk")
+pico_extras_path = File.join(r2p2_gem_dir, "lib/pico-extras")
+output_dir = File.join(REPOSITORY_ROOT, "build", build_name)
+mruby_build_dir = File.join(picoruby_root, "build", config_name)
+cmake_source_dir = File.join(r2p2_gem_dir, "cmake")
+
+unless File.file?(File.join(picoruby_root, "Rakefile"))
+  abort "PicoRuby source not found: #{picoruby_root}\nSet PICORUBY_DIR to a PicoRuby checkout."
+end
+abort "Build config not found: #{base_config_path}" unless File.file?(base_config_path)
+abort "Generated build config not found: #{config_path}" unless File.file?(config_path)
+build_config = File.read(base_config_path)
+mrubyc_vm = build_config.match?(/mrubyc_hal|conf\.femtoruby/)
+uses_wifi = build_config.match?(/\bUSE_WIFI\b/)
+command!("rake", "r2p2:setup", chdir: picoruby_root) unless File.directory?(pico_sdk_path)
+
+version_header = File.join(picoruby_root, "include/version.h")
+version = File.read(version_header)[/#define PICORUBY_VERSION "(.+?)"/, 1]
+abort "Could not determine PicoRuby version from #{version_header}" unless version
+abort "PicoRuby source is #{version}, but #{target_version} was requested." unless version == target_version
+
+cache_file = File.join(output_dir, "CMakeCache.txt")
+if File.file?(cache_file) && !File.read(cache_file).include?("CMAKE_HOME_DIRECTORY:INTERNAL=#{cmake_source_dir}")
+  puts "Removing stale CMake output: #{output_dir}"
+  FileUtils.rm_rf(output_dir)
+end
+FileUtils.mkdir_p(output_dir)
+build_env = {
+  "MRUBY_CONFIG" => config_path,
+  "PICORB_BOARD" => board,
+  "PICO_SDK_PATH" => pico_sdk_path,
+  "PICO_EXTRAS_PATH" => pico_extras_path
+}
+
+# PicoRuby's build directory is keyed by the target name, not by MRUBY_CONFIG.
+# A generated overlay therefore shares the base target's objects. In particular,
+# mrblib.c includes picogem_init.c, but Make does not track that generated include
+# as a dependency. Reusing the directory can leave a removed or added local
+# mrbgem out of libmruby.a. Custom mrbgems must start from a fresh target build.
+if fingerprint && File.directory?(mruby_build_dir)
+  puts "Removing stale PicoRuby build output: #{mruby_build_dir}"
+  FileUtils.rm_rf(mruby_build_dir)
+end
+command!("rake", chdir: picoruby_root, env: build_env)
+
+cmake_definitions = [
+  "-D", "PICORUBY_ROOT=#{picoruby_root}",
+  "-D", "R2P2_GEM_DIR=#{r2p2_gem_dir}",
+  "-D", "EXTRA_LIBRARY_PATH=#{File.join(mruby_build_dir, "lib")}",
+  "-D", "EXTRA_INCLUDE_DIR=#{File.join(mruby_build_dir, "include")}",
+  "-D", "PICO_CYW43_SUPPORTED=1",
+  "-D", "MRUBY_CONFIG=#{config_name}",
+  "-D", "PICORB_VM_MRUBY=#{mrubyc_vm ? 0 : 1}",
+  "-D", "PICORB_VM_MRUBYC=#{mrubyc_vm ? 1 : 0}",
+  "-D", "R2P2_NAME=R2P2-PICORUBY",
+  "-D", "R2P2_BOARD_NAME=#{board.upcase}",
+  "-D", "R2P2_VERSION=#{version}",
+  "-D", "PICO_PLATFORM=rp2350",
+  "-D", "PICO_BOARD=#{board}",
+  "-D", "CMAKE_BUILD_TYPE=Release",
+  "-D", "NDEBUG=1",
+  "-D", "R2P2_NO_SHARED_ALLOC=OFF"
+]
+cmake_definitions.push("-D", "USE_WIFI=1") if uses_wifi
+command!("cmake", "-S", cmake_source_dir, "-B", output_dir, *cmake_definitions,
+         chdir: picoruby_root, env: build_env)
+command!("cmake", "--build", output_dir, chdir: picoruby_root)
+
+uf2_files = Dir[File.join(output_dir, "*.uf2")]
+abort "Build finished but no UF2 file was created in #{output_dir}" if uf2_files.empty?
+
+built_firmware = uf2_files.max_by { |path| File.mtime(path) }
+destination = ENV.fetch("RPREMOTE_FIRMWARE", nil)
+if destination
+  FileUtils.mkdir_p(File.dirname(destination))
+  FileUtils.cp(built_firmware, destination)
+  puts "Built custom firmware: #{destination}"
+else
+  puts "Built custom firmware: #{built_firmware}"
+end

data/tasks/release.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "release_check"
+
+namespace :release do
+  desc "Validate and smoke-test the release gem without publishing it"
+  task check: %i[spec rubocop] do
+    sh "bundle exec rbs validate"
+    sh "gem build rpremote.gemspec"
+    Rpremote::ReleaseCheck.call
+  end
+end

data/tasks/release_check.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "bundler"
+require "open3"
+require "rbconfig"
+require "rubygems/package"
+require "tmpdir"
+require_relative "../lib/rpremote/version"
+
+module Rpremote
+  module ReleaseCheck
+    EXPECTED_FILES = %w[
+      CHANGELOG.md
+      LICENSE
+      README.md
+      README.ja.md
+      RELEASING.md
+      THIRD_PARTY_NOTICES.md
+      exe/rpremote
+      tasks/firmware_build.rb
+    ].freeze
+
+    module_function
+
+    def call
+      gem_file = File.expand_path("rpremote-#{Rpremote::VERSION}.gem")
+      validate_package(gem_file)
+      smoke_test(gem_file)
+      puts "release check passed: #{File.basename(gem_file)}"
+    end
+
+    def validate_package(gem_file)
+      package = Gem::Package.new(gem_file)
+      specification = package.spec
+      missing_files = EXPECTED_FILES - package.contents
+      changelog_entry = "## [#{Rpremote::VERSION}]"
+
+      unless specification.version.to_s == Rpremote::VERSION
+        abort "built gem version does not match #{Rpremote::VERSION}"
+      end
+      unless File.read("CHANGELOG.md").include?(changelog_entry)
+        abort "CHANGELOG.md has no entry for #{Rpremote::VERSION}"
+      end
+      abort "built gem is missing: #{missing_files.join(", ")}" unless missing_files.empty?
+      abort "built gem does not require MFA" unless specification.metadata["rubygems_mfa_required"] == "true"
+    end
+
+    def smoke_test(gem_file)
+      Dir.mktmpdir("rpremote-release-") do |directory|
+        gem_home = File.join(directory, "gems")
+        bin_dir = File.join(directory, "bin")
+        FileUtils.mkdir_p([gem_home, bin_dir])
+        environment = { "GEM_HOME" => gem_home, "GEM_PATH" => gem_home }
+
+        install_gem(environment, gem_home, bin_dir, gem_file)
+        run_cli(environment, bin_dir)
+      end
+    end
+
+    def install_gem(environment, gem_home, bin_dir, gem_file)
+      command = [
+        RbConfig.ruby, "-S", "gem", "install", "--local", "--no-document",
+        "--install-dir", gem_home, "--bindir", bin_dir, gem_file
+      ]
+      run!(environment, command, "isolated gem install")
+    end
+
+    def run_cli(environment, bin_dir)
+      stdout = run!(environment, [File.join(bin_dir, "rpremote"), "--version"], "installed CLI")
+      abort "installed CLI reported #{stdout.strip.inspect}" unless stdout.strip == Rpremote::VERSION
+    end
+
+    def run!(environment, command, description)
+      stdout, stderr, status = Bundler.with_unbundled_env do
+        Open3.capture3(environment, *command)
+      end
+      abort "#{description} failed:\n#{stdout}#{stderr}" unless status.success?
+
+      stdout
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: rpremote
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ogom
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Embed public or local mrbgems in reproducible R2P2 firmware, flash it,
+  and control the device.
+email:
+- ogom@users.noreply.github.com
+executables:
+- rpremote
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.ja.md
+- README.md
+- RELEASING.md
+- THIRD_PARTY_NOTICES.md
+- exe/rpremote
+- lib/rpremote.rb
+- lib/rpremote/build_command.rb
+- lib/rpremote/builder.rb
+- lib/rpremote/checksum.rb
+- lib/rpremote/cli.rb
+- lib/rpremote/config.rb
+- lib/rpremote/device.rb
+- lib/rpremote/dfu_command.rb
+- lib/rpremote/dfu_compiler.rb
+- lib/rpremote/flash_command.rb
+- lib/rpremote/flasher.rb
+- lib/rpremote/help.rb
+- lib/rpremote/language.rb
+- lib/rpremote/language_source.rb
+- lib/rpremote/mrbgems.rb
+- lib/rpremote/mrbgems_command.rb
+- lib/rpremote/picomodem.rb
+- lib/rpremote/remote_path.rb
+- lib/rpremote/resetter.rb
+- lib/rpremote/runner.rb
+- lib/rpremote/serial.rb
+- lib/rpremote/setup_command.rb
+- lib/rpremote/shell.rb
+- lib/rpremote/target.rb
+- lib/rpremote/terminal.rb
+- lib/rpremote/version.rb
+- sig/rpremote.rbs
+- tasks/firmware_build.rb
+- tasks/release.rake
+- tasks/release_check.rb
+homepage: https://github.com/ogom/rpremote
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ogom/rpremote
+  source_code_uri: https://github.com/ogom/rpremote/tree/main/packages/rpremote
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Build and control custom PicoRuby firmware on Raspberry Pi Pico
+test_files: []