uprb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5935681ab015986fc8fa6aa5aad5d660da25e6126602888b95929f8456216f8b
+  data.tar.gz: c59b6d98633c40d506852dca47e4bf1895baaece4fcb596c4bf1e2cf62392dea
+SHA512:
+  metadata.gz: cfeb194da679b6b6826c21f7207128869d835496268051d27e292e09f74edaaff60ca04381c5db3b63e268770924904d5cbfa0bca84055460fe4ef934e09f568
+  data.tar.gz: f09e358a5ffd2b2d22c1ca1dc26669be9d21d8bdc141aa59ed13e6480203c4e1b97c246944495d88a7e8cf80a53fb9029baa3e41f33bdfea7d4e44d8821f770f

data/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. User-facing docs live in `README.md`.
+
+## Commands
+
+- `bin/setup` — `bundle install`.
+- `bundle exec rake` — run the full test suite.
+- `bundle exec ruby -Itest test/test_uprb_cli.rb -n test_pack_builds_executable` — run a single test by name.
+- `bundle exec exe/uprb pack path/to/script.rb path/to/out` — run the CLI from the working tree.
+
+Ruby 3.1+ (`uprb.gemspec`). CI: 3.4.7.
+
+## What uprb does
+
+Packs a Ruby script into a deterministic, fast-starting executable by **freezing every observed `require` at pack time**. At runtime, the frozen mapping is preferred; anything else falls through to Ruby's normal `require`. If the environment changes, the executable is expected to break — the only remediation is repack.
+
+## Architecture
+
+- `lib/uprb/require_tracker.rb` — aliases `Kernel#require` / `Kernel#require_relative` and records `name => $LOADED_FEATURES` path on every successful call.
+- `lib/uprb/static_require_tracker.rb` — the **default** tracer. Two passes: (1) parse the entry with Prism and actually `require` each literal require/autoload target — libraries load normally but the entry's other top-level code (e.g. `App.start(ARGV)`) does not run, and everything pulled in transitively is recorded via `RequireTracker`; (2) `StaticWalker` recursively parses every reachable `.rb` file to pick up literal requires and autoload paths that the runtime never hit (rescued `LoadError` alternates, unused autoloads, feature-flag branches). The merged map uses dynamic results on conflict since those reflect the actually-resolved path. Interpolated-string requires triggered only by runtime execution (e.g. `require "foo/#{name}"` inside a method called by the entry) are still missed — those need `--dynamic`.
+- `lib/uprb/require_replacer.rb` — `pack` builds the mapping via `build_mapping` (default: `StaticRequireTracker.trace`; `--dynamic`: `execute_with_tracker` + `StaticWalker` as a second pass so the runtime-only captures are augmented with literal/autoload paths not exercised by the execution). Then compiles the main script and every `.rb` entry into `RubyVM::InstructionSequence` binaries and appends a `Marshal` payload after `__END__`. A prepended `FixedRequire` module serves embedded ISeqs; non-`.rb` requires (C extensions etc.) are resolved via a `REQUIRE_MAP` of original absolute paths; unknown names defer to `super`. `execute_with_tracker` captures stdout/stderr to `Tempfile`, clears `ARGV`, sets `$PROGRAM_NAME`, and `Kernel#load`s the source in-process.
+- `lib/uprb/cli.rb`, `exe/uprb` — CLI: `pack`, `gem install`, `gem pack`. Options: `--path DIR` (gem subcommands; default `Gem.bindir`).
+
+The output gets a shebang only when the source does. With a source shebang, the wrapper's shebang is the absolute `RbConfig.ruby` path plus `--disable-gems` by default. Two orthogonal opt-outs:
+
+- `--skip-disable-gems` drops the `--disable-gems` flag so the output starts Ruby normally (rubygems / `RUBYOPT` / Bundler Gemfile autodetection all active) — intended for vendoring-only use cases that accept normal startup cost.
+- `--skip-ruby-path-replace` keeps the source file's shebang ruby invocation verbatim (e.g. `/usr/bin/env ruby`) instead of rewriting it to `RbConfig.ruby` — intended for vendoring that wants a portable Ruby reference in the output.
+
+The two flags can be combined (e.g. `#!/usr/bin/env ruby` with no `--disable-gems`). When the source has no shebang, the packed output also has none and is not chmod'd executable — invoke via `ruby packed_file`. This is uniform across all flag combinations.
+
+## Hard constraints on the generated executable
+
+Any change to the output generator must preserve these — violating any is a bug:
+
+- Absolute `RbConfig.ruby` path in the shebang by default; never `/usr/bin/env ruby`, never a PATH lookup. `--skip-ruby-path-replace` is the one documented opt-out, for vendoring-only outputs that preserve the source's shebang ruby invocation
+- `--disable-gems` in the shebang by default; rubygems is not available at runtime. `--skip-disable-gems` is the one documented opt-out, for vendoring-only outputs that accept normal Ruby startup cost
+- No `-I`, no `$LOAD_PATH` modification, no `RUBYLIB`, no Bundler
+- `.rb` dependencies are always embedded as ISeq binaries inside the `Marshal` payload; C extensions and other non-`.rb` requires are always referenced by their **original absolute path** via `REQUIRE_MAP` — never copied, never relocated
+
+## Non-goals
+
+Declining these is a design choice, not a todo:
+
+- Bundling Ruby itself; vendoring C extensions; cross-machine portability
+- Surviving Ruby/gem upgrades, graceful degradation
+- Plugin systems or dynamic resolution beyond the frozen mapping
+
+(Compiled `.rb` sources are embedded in the output, so it is *partially* self-contained for pure-Ruby deps. C extensions and the Ruby interpreter are still referenced by absolute path, so the output remains tied to the machine it was packed on.)
+
+The output is expected to break when the Ruby path moves, C extension paths change, gems are up/downgraded, or new code paths hit unseen `require`s. The only remediation is `uprb pack <src> <dest>`.
+
+## Testing notes
+
+`test/test_uprb_cli.rb` shells out to `exe/uprb` via `Open3` and writes artifacts under `./tmp/` (gitignored). `aws-sdk-core` is a dev dependency so the suite can verify that a library pulling in rubygems vendored stdlib still packs successfully; the packed output itself is not runnable under `--disable-gems` and is not executed by the test. `examples/rls` and `examples/s3-ls` are sample gems, not part of the suite. `examples/s3-ls` depends on `aws-sdk-s3` and is kept as a reference — with a bare `uprb gem pack` it won't run under `--disable-gems`, but `uprb gem pack s3-ls --with-rubygems --dynamic` runs it up to the AWS credential/region resolution path (see `examples/s3-ls/README.md`).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 hogelog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# uprb
+
+uprb is a Ruby script packer. It builds a single executable from a Ruby
+script with a fast, deterministic startup.
+
+This is not a native binary compiler. The packed executable still needs
+a Ruby interpreter on the machine that runs it, and it is tied to the
+Ruby and gems that were active when you packed.
+
+The packed executable starts Ruby with `--disable-gems` by default.
+Gems that depend on rubygems at load time will not work as-is — use
+`--with-rubygems` to embed rubygems into the output, or
+`--skip-disable-gems` to drop the flag entirely (vendoring only; gives
+up the fast-startup headline).
+
+## Usage
+
+Pack a script into a single executable:
+
+```bash
+uprb pack path/to/script.rb path/to/output
+```
+
+Options:
+
+- `-f`, `--force`: overwrite the destination without prompting
+- `-r`, `--require LIB`: pre-`require` `LIB` so it is embedded and loaded before the script runs. Repeatable.
+- `--with-rubygems`: shortcut for `--require rubygems`. Needed when the script references `Gem::Version` / `Gem::Requirement` / `Gem::Platform` etc. Trade-off: larger output.
+- `--dynamic`: execute the entry script at pack time so runtime-only requires (e.g. interpolated `require`s) are captured. The entry actually runs, which is a problem for scripts that do I/O on startup — arguments after `--` are forwarded as `ARGV` so you can steer into a safe path (e.g. `-- --help`).
+- `--skip-disable-gems`: drop `--disable-gems` from the shebang. The output then behaves like a normal Ruby invocation — rubygems, `RUBYOPT`, and Bundler's Gemfile autodetection all run as usual. Use this when you want single-file vendoring of `.rb` dependencies and don't care about startup latency.
+- `--skip-ruby-path-replace`: keep the source file's shebang ruby invocation (e.g. `/usr/bin/env ruby`) instead of rewriting it to an absolute `RbConfig.ruby` path. `--disable-gems` is still appended (unless `--skip-disable-gems` is also passed), so this is orthogonal to `--skip-disable-gems`. Use for vendoring when you want a portable Ruby reference in the output.
+
+If the source has no shebang, the packed output also has no shebang and is not chmod'd executable — invoke via `ruby packed_file`. This applies regardless of flags.
+
+Pack executables from an installed gem:
+
+```bash
+uprb gem pack GEM_NAME
+```
+
+Install a gem and pack its executables:
+
+```bash
+uprb gem install GEM_NAME
+```
+
+Both `gem` subcommands accept `--path DIR` (destination directory),
+`-f`/`--force`, `-r`/`--require LIB`, `--with-rubygems`, `--dynamic`,
+`--skip-disable-gems`, and `--skip-ruby-path-replace`.
+
+By default, `uprb` asks `overwrite? [y/N]` on stderr when the
+destination already exists. When stdin is not a TTY (e.g. CI), `uprb`
+refuses to overwrite unless `--force` is given.
+
+## Install
+
+```bash
+gem install uprb
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/examples/rls/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/examples/rls/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rls.gemspec
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"

data/examples/rls/README.md

@@ -0,0 +1,9 @@
+# rls
+
+Example ls command written by ruby.
+
+## Usage
+
+```bash
+rls
+```

data/examples/rls/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/examples/rls/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "rls"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/examples/rls/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/rls/exe/rls

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "rls"
+
+Rls::CLI.start(ARGV)

data/examples/rls/lib/rls/cli.rb

@@ -0,0 +1,48 @@
+module Rls
+  class CLI
+    USAGE = <<~USAGE.chomp
+    Usage:
+      rls [path]
+    USAGE
+
+    class << self
+      def start(argv)
+        new(argv).start
+      end
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def start
+      arg = @argv.shift
+
+      case arg
+      when "--help", "-h"
+        STDOUT.puts(USAGE)
+      when nil
+        ls_command
+      else
+        ls_command(arg)
+      end
+    rescue Rls::Error => e
+      STDERR.puts("rls: #{e.message}")
+    rescue StandardError => e
+      STDERR.puts("rls: #{e.class}: #{e.message}")
+    end
+
+    private
+
+    def ls_command(path = ".")
+      raise Rls::Error, "unexpected arguments: #{@argv.join(' ')}" unless @argv.empty?
+
+      abs_path = File.expand_path(path)
+      raise Rls::Error, "not a directory: #{path}" unless File.directory?(abs_path)
+
+      Dir.children(abs_path).sort.each do |entry|
+        STDOUT.puts(entry)
+      end
+    end
+  end
+end

data/examples/rls/lib/rls/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rls
+  VERSION = "0.1.0"
+end

data/examples/rls/lib/rls.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "rls/version"
+require_relative "rls/cli"
+
+module Rls
+  class Error < StandardError; end
+end

data/examples/rls/rls.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/rls/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rls"
+  spec.version = Rls::VERSION
+  spec.authors = ["hogelog"]
+  spec.email = ["konbu.komuro@gmail.com"]
+
+  spec.summary = "Example ls command gem"
+  spec.description = "Example ls command gem"
+  spec.homepage = "https://github.com/hogelog/uprb"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  gemspec = File.basename(__FILE__)
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      (f == gemspec) ||
+        f.start_with?(*%w[bin/ Gemfile .gitignore])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) {|f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/examples/rls/sig/rls.rbs

@@ -0,0 +1,4 @@
+module Rls
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/examples/s3-ls/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/examples/s3-ls/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in s3-ls.gemspec
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"

data/examples/s3-ls/Gemfile.lock

@@ -0,0 +1,91 @@
+PATH
+  remote: .
+  specs:
+    s3-ls (0.1.0)
+      aws-sdk-s3 (>= 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aws-eventstream (1.4.0)
+    aws-partitions (1.1202.0)
+    aws-sdk-core (3.241.3)
+      aws-eventstream (~> 1, >= 1.3.0)
+      aws-partitions (~> 1, >= 1.992.0)
+      aws-sigv4 (~> 1.9)
+      base64
+      bigdecimal
+      jmespath (~> 1, >= 1.6.1)
+      logger
+    aws-sdk-kms (1.120.0)
+      aws-sdk-core (~> 3, >= 3.241.3)
+      aws-sigv4 (~> 1.5)
+    aws-sdk-s3 (1.211.0)
+      aws-sdk-core (~> 3, >= 3.241.3)
+      aws-sdk-kms (~> 1)
+      aws-sigv4 (~> 1.5)
+    aws-sigv4 (1.12.1)
+      aws-eventstream (~> 1, >= 1.0.2)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    date (3.5.1)
+    erb (6.0.1)
+    io-console (0.8.2)
+    irb (1.16.0)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    jmespath (1.6.2)
+    logger (1.7.0)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.3.1)
+      date
+      stringio
+    rake (13.3.1)
+    rdoc (7.0.3)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    stringio (3.2.0)
+    tsort (0.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  irb
+  rake (~> 13.0)
+  s3-ls!
+
+CHECKSUMS
+  aws-eventstream (1.4.0) sha256=116bf85c436200d1060811e6f5d2d40c88f65448f2125bc77ffce5121e6e183b
+  aws-partitions (1.1202.0) sha256=c8aa0f134a23464c61cfd00edfb4b6d968b01847a8b591d4dcc0c63a4897c301
+  aws-sdk-core (3.241.3) sha256=c7c445ecf1c601c860fd537458b2eb8df0c5df01e63c371849e6594e6b1d4f47
+  aws-sdk-kms (1.120.0) sha256=a206ac6f62efbe971f802e8399d2702496a5c5bc800abcf94ead87bdddfdfd80
+  aws-sdk-s3 (1.211.0) sha256=2ae5feb09ff4862462824f267b76601ed16922a15de56cf51e4fa99bc5b3f519
+  aws-sigv4 (1.12.1) sha256=6973ff95cb0fd0dc58ba26e90e9510a2219525d07620c8babeb70ef831826c00
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
+  jmespath (1.6.2) sha256=238d774a58723d6c090494c8879b5e9918c19485f7e840f2c1c7532cf84ebcb1
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rdoc (7.0.3) sha256=dfe3d0981d19b7bba71d9dbaeb57c9f4e3a7a4103162148a559c4fc687ea81f9
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  s3-ls (0.1.0)
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+
+BUNDLED WITH
+  4.0.3

data/examples/s3-ls/README.md

@@ -0,0 +1,19 @@
+# s3-ls
+
+Example S3 ls command gem.
+
+## Usage
+
+```bash
+s3-ls s3://bucket[/prefix]
+```
+
+## Packing with uprb
+
+`aws-sdk-core` pulls in rubygems vendored stdlib, so embed rubygems with `--with-rubygems`. Its credential provider chain uses runtime-only interpolated requires (e.g. `aws-sdk-core/json/#{name}_engine`), so pack in `--dynamic` mode so the entry actually runs and those requires fire:
+
+```bash
+uprb gem pack s3-ls --with-rubygems --dynamic --path ~/local/bin/
+```
+
+`--dynamic` also augments its trace with a static walk of every reachable `.rb`, so literal requires in unexecuted credential-provider branches get embedded too. If a runtime path still falls through to something that wasn't observed or statically reachable, repack with additional `-r` flags for the missing libs.

data/examples/s3-ls/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/examples/s3-ls/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "s3/ls"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/examples/s3-ls/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/s3-ls/exe/s3-ls

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "s3/ls/cli"
+
+S3::Ls::CLI.start(ARGV)

data/examples/s3-ls/lib/s3/ls/cli.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "uri"
+require "aws-sdk-s3"
+require_relative "../ls"
+
+module S3
+  module Ls
+    class CLI
+      USAGE = <<~USAGE.chomp
+      Usage:
+        s3-ls s3://bucket[/prefix]
+        s3-ls -h | --help
+      USAGE
+
+      def self.start(argv)
+        new(argv).start
+      end
+
+      def initialize(argv)
+        @argv = argv.dup
+      end
+
+      def start
+        if @argv.first == "-h" || @argv.first == "--help"
+          $stdout.puts USAGE
+          return
+        end
+
+        client = Aws::S3::Client.new
+
+        if @argv.empty?
+          list_buckets(client)
+        else
+          uri = @argv.shift
+          bucket, prefix = parse_s3_uri(uri)
+          list_objects(client, bucket, prefix)
+        end
+      rescue S3::Ls::Error => e
+        $stderr.puts "s3-ls: #{e.message}"
+        exit 1
+      rescue StandardError => e
+        $stderr.puts "s3-ls: #{e.class}: #{e.message}"
+        exit 1
+      end
+
+      private
+
+      def list_objects(client, bucket, prefix)
+        client.list_objects_v2(bucket: bucket, prefix: prefix).each_page do |page|
+          page.contents.each do |object|
+            $stdout.puts "s3://#{bucket}/#{object.key}"
+          end
+        end
+      end
+
+      def list_buckets(client)
+        client.list_buckets.buckets.each do |bucket|
+          $stdout.puts "s3://#{bucket.name}"
+        end
+      end
+
+      def parse_s3_uri(input)
+        uri = URI.parse(input)
+        raise S3::Ls::Error, "invalid s3 uri: #{input}" unless uri.scheme == "s3"
+        raise S3::Ls::Error, "missing bucket in s3 uri: #{input}" if uri.host.to_s.empty?
+
+        bucket = uri.host
+        prefix = uri.path
+        prefix = prefix.sub(%r{\A/}, "")
+        prefix = nil if prefix.empty?
+        [bucket, prefix]
+      rescue URI::InvalidURIError
+        raise S3::Ls::Error, "invalid s3 uri: #{input}"
+      end
+    end
+  end
+end

data/examples/s3-ls/lib/s3/ls/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module S3
+  module Ls
+    VERSION = "0.1.0"
+  end
+end

data/examples/s3-ls/lib/s3/ls.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "ls/version"
+require_relative "ls/cli"
+
+module S3
+  module Ls
+    class Error < StandardError; end
+  end
+end

data/examples/s3-ls/s3-ls.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/s3/ls/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "s3-ls"
+  spec.version = S3::Ls::VERSION
+  spec.authors = ["hogelog"]
+  spec.email = ["konbu.komuro@gmail.com"]
+
+  spec.summary = "Example S3 ls command gem"
+  spec.description = "Example S3 ls command gem"
+  spec.homepage = "https://github.com/hogelog/uprb"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  gemspec = File.basename(__FILE__)
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      (f == gemspec) ||
+        f.start_with?(*%w[bin/ Gemfile .gitignore])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) {|f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "aws-sdk-s3", ">= 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/examples/s3-ls/sig/s3/ls.rbs

@@ -0,0 +1,6 @@
+module S3
+  module Ls
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/exe/uprb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "uprb/cli"
+
+Uprb::CLI.start(ARGV)