ruby_wasm_ic_installer 0.1.0

data/lib/ruby_wasm_ic_installer/canister.rb

@@ -0,0 +1,208 @@
+# ruby_wasm_ic_installer/canister.rb: the Installer's canister half, carried
+# by an Application (packed under /app, so it is there before anything is
+# installed) and required at the top of its app.rb. `ruby_wasm_ic_installer
+# setup <app_dir>` writes that require and the Declarations it serves.
+#
+# Core Ruby and the builder's IC only (IC.caller, IC.refuse, IC::DATA_DIR):
+# it loads on a `minimal` canister, so it names no Encoding constant and
+# requires nothing.
+#
+# The layout it keeps (W29, Q7 to Q11):
+#   /data/gems/<name>-<version>/...     one directory per gem version, complete
+#   /data/gems/.partial/<name>-<version>/  a version still arriving
+#   /data/setup.rb                      the setup file: its generation and the
+#                                       load paths, required at boot
+# A version arrives into .partial by install_put and is renamed into place by
+# install_commit, which also writes the setup file, last, once every gem it
+# names is complete. A new setup file takes effect at the next boot. A version
+# is removed only by install_remove, and never while the running boot or the
+# pending one names it. Every method is for the canister's controllers only.
+module RubyWasmIcInstaller
+  module Canister
+    # A gem version's directory: a gem name, a dash, a version.
+    NAME_VERSION = /\A[A-Za-z0-9][A-Za-z0-9_.\-]*-[0-9][A-Za-z0-9_.\-]*\z/
+    SETUP_HEAD = "# generated by ruby_wasm_ic_installer: do not edit, it is rewritten by install_commit\n"
+    GENERATION_LINE = /\A# generation: (\d+)$/
+
+    class << self
+      # The running generation (the setup file this boot loaded), or nil.
+      attr_reader :running_generation
+
+      def data_dir = @data_dir || IC::DATA_DIR
+      attr_writer :data_dir
+
+      def gems_dir = File.join(data_dir, "gems")
+      def partial_dir = File.join(gems_dir, ".partial")
+      def setup_file = File.join(data_dir, "setup.rb")
+
+      # At boot: load the setup file if there is one. It calls #setup below.
+      def boot!
+        @running_generation = nil
+        @running_paths = []
+        load(setup_file) if File.file?(setup_file)
+        self
+      end
+
+      # Called by the setup file: puts its load paths on $LOAD_PATH, after
+      # /app (so a Carried library still shadows an installed one) and before
+      # the Shipped library, in the lock's order.
+      def setup(generation, load_paths)
+        @running_generation = generation
+        @running_paths = load_paths.map { |p| File.join(gems_dir, p) }
+        app = $LOAD_PATH.rindex { |p| p == "/app" || p.start_with?("/app/") }
+        $LOAD_PATH.insert(app ? app + 1 : 0, *(@running_paths - $LOAD_PATH))
+        nil
+      end
+
+      # install_put: files into .partial/<name-version>/, each path
+      # "<name-version>/<path inside the gem>".
+      def put(files)
+        controller!
+        files.each do |f|
+          nv, rest = split!(f[:path])
+          full = File.join(partial_dir, nv, rest)
+          mkdir_p(File.dirname(full))
+          File.binwrite(full, f[:body])
+        end
+        "wrote #{files.size} files, #{files.sum { _1[:body].bytesize }} bytes"
+      end
+
+      # install_commit: rename each named .partial directory into place, then
+      # write the setup file if one is given, whose every load path must be
+      # inside a complete version.
+      def commit(request)
+        controller!
+        done = request[:gems].map do |nv|
+          name_version!(nv)
+          from = File.join(partial_dir, nv)
+          to = File.join(gems_dir, nv)
+          IC.refuse("#{nv} has nothing in .partial to commit") unless File.directory?(from)
+          IC.refuse("#{nv} is already installed") if File.exist?(to)
+          File.rename(from, to)
+          nv
+        end
+        msg = "committed #{done.size} gems"
+        setup = request[:setup]
+        return msg unless setup
+
+        write_setup!(setup[:generation], setup[:load_paths])
+        "#{msg}; wrote setup generation #{setup[:generation]}"
+      end
+
+      # install_remove: delete one complete version that neither the running
+      # boot nor the pending setup file names, or a leftover in .partial.
+      def remove(nv)
+        controller!
+        name_version!(nv)
+        if File.directory?(File.join(partial_dir, nv)) && !File.exist?(File.join(gems_dir, nv))
+          rm_r(File.join(partial_dir, nv))
+          return "removed #{nv} from .partial"
+        end
+        dir = File.join(gems_dir, nv)
+        IC.refuse("#{nv} is not installed") unless File.directory?(dir)
+        IC.refuse("#{nv} is named by the running boot (generation #{running_generation})") if named?(running_names, nv)
+        IC.refuse("#{nv} is named by the pending setup (generation #{pending_generation})") if named?(pending_names, nv)
+        rm_r(dir)
+        "removed #{nv}"
+      end
+
+      # installed: public, a query. What runs and what is waiting.
+      def installed
+        {
+          running: running_generation,
+          pending: pending_generation,
+          gems: list(gems_dir),
+          partial: list(partial_dir),
+          load_paths: pending_paths,
+          running_paths: (@running_paths || []).map { _1.delete_prefix("#{gems_dir}/") }
+        }
+      end
+
+      def pending_generation
+        return nil unless File.file?(setup_file)
+
+        File.foreach(setup_file) { |l| return Regexp.last_match(1).to_i if l =~ GENERATION_LINE }
+        nil
+      end
+
+      private
+
+      def controller!
+        IC.caller.controller? || IC.refuse("only a controller may install code")
+      end
+
+      def name_version!(nv)
+        IC.refuse("not a gem version directory: #{nv.inspect}") unless nv.is_a?(String) && nv =~ NAME_VERSION
+        nv
+      end
+
+      # "<name-version>/<rest>", with no absolute path, no "..", no "." and
+      # no empty segment.
+      def split!(path)
+        IC.refuse("path must be relative: #{path}") if path.start_with?("/")
+        parts = path.split("/", -1)
+        IC.refuse("path must not hold . or .. or an empty segment: #{path}") if parts.any? { ["", ".", ".."].include?(_1) }
+        IC.refuse("path must be <name-version>/<file>: #{path}") if parts.size < 2
+        [name_version!(parts.first), parts.drop(1).join("/")]
+      end
+
+      def write_setup!(generation, load_paths)
+        unless generation.is_a?(Integer) && generation > (pending_generation || 0) && generation > (running_generation || 0)
+          IC.refuse("setup generation #{generation} must be above the pending (#{pending_generation.inspect}) " \
+                    "and running (#{running_generation.inspect}) ones")
+        end
+        load_paths.each do |p|
+          nv, = split!(p)
+          IC.refuse("load path #{p} is not inside an installed gem") unless File.directory?(File.join(gems_dir, p)) &&
+                                                                             File.directory?(File.join(gems_dir, nv))
+        end
+        body = SETUP_HEAD + "# generation: #{generation}\n" \
+               "RubyWasmIcInstaller::Canister.setup(#{generation}, #{load_paths.map(&:to_s).inspect})\n"
+        File.write(setup_file, body)
+      end
+
+      def pending_paths
+        return [] unless File.file?(setup_file)
+
+        line = File.foreach(setup_file).find { _1.start_with?("RubyWasmIcInstaller::Canister.setup(") }
+        return [] unless line
+
+        line.scan(/"((?:[^"\\]|\\.)*)"/).map(&:first)
+      end
+
+      def running_names = (@running_paths || []).map { |p| p.delete_prefix("#{gems_dir}/").split("/").first }
+      def pending_names = pending_paths.map { _1.split("/").first }
+      def named?(names, nv) = names.include?(nv)
+
+      def list(dir)
+        return [] unless File.directory?(dir)
+
+        Dir.children(dir).reject { _1.start_with?(".") }.select { File.directory?(File.join(dir, _1)) }.sort
+      end
+
+      def mkdir_p(dir)
+        return if File.directory?(dir)
+
+        mkdir_p(File.dirname(dir))
+        Dir.mkdir(dir)
+      end
+
+      def rm_r(path)
+        if File.directory?(path) && !File.symlink?(path)
+          Dir.children(path).each { rm_r(File.join(path, _1)) }
+          Dir.rmdir(path)
+        else
+          File.delete(path)
+        end
+      end
+    end
+  end
+end
+
+# The Declarations `setup` writes into ic-interface.rb are served by these.
+def install_put(files) = RubyWasmIcInstaller::Canister.put(files)
+def install_commit(request) = RubyWasmIcInstaller::Canister.commit(request)
+def install_remove(name_version) = RubyWasmIcInstaller::Canister.remove(name_version)
+def installed = RubyWasmIcInstaller::Canister.installed
+
+RubyWasmIcInstaller::Canister.boot! if defined?(IC::DATA_DIR)

data/lib/ruby_wasm_ic_installer/cli.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RubyWasmIcInstaller
+  # The command: `ruby_wasm_ic_installer <install|status|prune|setup> ...`.
+  class CLI
+    USAGE = <<~TEXT
+      Usage:
+        ruby_wasm_ic_installer install CANISTER [--lock Gemfile.lock] [--dry-run] [icp options]
+        ruby_wasm_ic_installer status  CANISTER [icp options]
+        ruby_wasm_ic_installer prune   CANISTER [--dry-run] [icp options]
+        ruby_wasm_ic_installer setup   APP_DIR  [--yes | --check]
+
+      install  sends the lock's pure-Ruby gems the canister lacks, then the setup
+               file that loads them; it takes effect at the next upgrade
+      status   what the canister has installed, running and pending
+      prune    removes every version neither the running nor the pending setup names
+      setup    wires the Installer's methods into an Application (ic-interface.rb,
+               app.rb, vendor/ruby_wasm_ic_installer/)
+
+      icp options, passed to `icp canister call`:
+        -e, --environment ENV   -n, --network NETWORK   --identity NAME
+        --project-root DIR      the icp project (icp's --project-root-override)
+        --icp PATH              the icp command (default: icp)
+      Other options:
+        --cache DIR             where fetched .gem files are kept
+                                (default: ~/.cache/ruby_wasm_ic_installer)
+        --budget BYTES          the largest batch, in bytes of Candid (default: #{Plan::DEFAULT_BUDGET})
+        -h, --help, --version
+    TEXT
+
+    def self.start(argv, out: $stdout, err: $stderr, input: $stdin, runner: nil, gem_files: nil)
+      new(out: out, err: err, input: input, runner: runner, gem_files: gem_files).run(argv)
+    end
+
+    def initialize(out:, err:, input:, runner:, gem_files:)
+      @out = out
+      @err = err
+      @input = input
+      @runner = runner
+      @gem_files = gem_files
+    end
+
+    # The exit status.
+    def run(argv)
+      opts = { lock: "Gemfile.lock", icp: "icp", icp_args: [], dry_run: false, yes: false, check: false,
+               cache: File.join(Dir.home, ".cache", "ruby_wasm_ic_installer"), budget: Plan::DEFAULT_BUDGET }
+      args = parser(opts).parse(argv)
+      return 0 if opts[:done]
+
+      command = args.shift
+      target = args.shift
+      raise Error, "#{USAGE}\nunexpected: #{args.join(' ')}" unless args.empty?
+      raise Error, USAGE if command.nil? || target.nil?
+
+      case command
+      when "setup" then setup(target, opts)
+      when "install" then report(installer(target, opts).install(Lockfile.read(opts[:lock]), dry_run: opts[:dry_run]))
+      when "status" then report(installer(target, opts).status)
+      when "prune" then report(installer(target, opts).prune(dry_run: opts[:dry_run]))
+      else raise Error, "#{USAGE}\nunknown command: #{command}"
+      end
+    rescue Error, OptionParser::ParseError => e
+      @err.puts(e.message)
+      e.is_a?(Runner::CallError) || e.is_a?(AppSetup::Aborted) ? 1 : 2
+    end
+
+    private
+
+    def parser(opts)
+      OptionParser.new do |o|
+        o.banner = USAGE
+        o.on("--lock PATH") { opts[:lock] = _1 }
+        o.on("--dry-run") { opts[:dry_run] = true }
+        o.on("--yes") { opts[:yes] = true }
+        o.on("--check") { opts[:check] = true }
+        o.on("--icp PATH") { opts[:icp] = _1 }
+        o.on("--cache DIR") { opts[:cache] = _1 }
+        o.on("--budget BYTES", Integer) { opts[:budget] = _1 }
+        o.on("-e", "--environment ENV") { opts[:icp_args] += ["-e", _1] }
+        o.on("-n", "--network NETWORK") { opts[:icp_args] += ["-n", _1] }
+        o.on("--identity NAME") { opts[:icp_args] += ["--identity", _1] }
+        o.on("--project-root DIR") { opts[:icp_args] += ["--project-root-override", _1] }
+        o.on("-h", "--help") { @out.puts(USAGE) || opts[:done] = true }
+        o.on("--version") { @out.puts(VERSION) || opts[:done] = true }
+      end
+    end
+
+    def installer(canister, opts)
+      runner = @runner || Runner.new(canister: canister, icp: opts[:icp], icp_args: opts[:icp_args])
+      Installer.new(runner: runner, gem_files: @gem_files || GemFiles.new(cache: opts[:cache]), budget: opts[:budget])
+    end
+
+    def setup(dir, opts)
+      s = AppSetup.new(dir, io: @out, input: @input)
+      return s.check if opts[:check]
+
+      s.run(yes: opts[:yes])
+      0
+    end
+
+    def report(lines)
+      lines.each { @out.puts(_1) }
+      0
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/diff.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyWasmIcInstaller
+  # A unified diff of two texts by lines, enough for `setup` to show what it
+  # would change (W29, Q17). Longest common subsequence; three lines of
+  # context; no dependency.
+  module Diff
+    module_function
+
+    def unified(old_text, new_text, from:, to:, context: 3)
+      a = old_text.lines
+      b = new_text.lines
+      ops = edits(a, b)
+      return "" if ops.all? { _1.first == :same }
+
+      out = +"--- #{from}\n+++ #{to}\n"
+      hunks(ops, context).each do |h|
+        a_start = h.first[2] + 1
+        b_start = h.first[3] + 1
+        a_len = h.count { _1.first != :add }
+        b_len = h.count { _1.first != :del }
+        out << "@@ -#{a_len.zero? ? a_start - 1 : a_start},#{a_len} +#{b_len.zero? ? b_start - 1 : b_start},#{b_len} @@\n"
+        h.each do |op, line, *|
+          mark = { same: " ", del: "-", add: "+" }.fetch(op)
+          out << mark << line
+          out << "\n\\n" unless line.end_with?("\n")
+        end
+      end
+      out
+    end
+
+    # [[op, line, index in a, index in b], ...] in order.
+    def edits(a, b)
+      lcs = Array.new(a.size + 1) { Array.new(b.size + 1, 0) }
+      (a.size - 1).downto(0) do |i|
+        (b.size - 1).downto(0) do |j|
+          lcs[i][j] = a[i] == b[j] ? lcs[i + 1][j + 1] + 1 : [lcs[i + 1][j], lcs[i][j + 1]].max
+        end
+      end
+      i = j = 0
+      ops = []
+      while i < a.size || j < b.size
+        if i < a.size && j < b.size && a[i] == b[j]
+          ops << [:same, a[i], i, j]
+          i += 1
+          j += 1
+        elsif i < a.size && (j == b.size || lcs[i + 1][j] >= lcs[i][j + 1])
+          ops << [:del, a[i], i, j] # a deletion first, as diff(1) prints it
+          i += 1
+        else
+          ops << [:add, b[j], i, j]
+          j += 1
+        end
+      end
+      ops
+    end
+
+    def hunks(ops, context)
+      changed = ops.each_index.reject { ops[_1].first == :same }
+      groups = []
+      changed.each do |k|
+        lo = [k - context, 0].max
+        hi = [k + context, ops.size - 1].min
+        if groups.any? && lo <= groups.last.last + 1
+          groups.last[1] = hi
+        else
+          groups << [lo, hi]
+        end
+      end
+      groups.map { |lo, hi| ops[lo..hi] }
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/gem_files.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "open3"
+require "rubygems/package"
+require "tmpdir"
+
+module RubyWasmIcInstaller
+  # One locked gem made ready to send (W29, Q8 and Q9): its `.gem` fetched
+  # for platform `ruby` (or found in the cache), checked against the lock's
+  # sha256 when the lock has one, refused if it has extensions, and opened
+  # for its require_paths alone, with magic comments fixed.
+  class GemFiles
+    Prepared = Struct.new(:name_version, :require_paths, :files, :rewrites, keyword_init: true) do
+      def bytes = files.sum { _2.bytesize }
+    end
+
+    class Refused < Error; end
+
+    # `fetcher` is called as fetcher.(name, version, dir) and must leave
+    # "<name>-<version>.gem" in dir; the default runs `gem fetch`.
+    def initialize(cache:, fetcher: nil)
+      @cache = cache
+      @fetcher = fetcher || method(:gem_fetch)
+    end
+
+    def prepare(locked)
+      path = fetch(locked)
+      check_sum!(locked, path)
+      package = ::Gem::Package.new(path)
+      spec = package.spec
+      check_spec!(locked, spec)
+      files, rewrites = read_files(locked, package, spec)
+      paths = spec.require_paths.select { |rp| files.keys.any? { _1.start_with?("#{rp}/") } }
+      raise Refused, "#{locked.name_version} has no files under #{spec.require_paths.join(', ')}" if paths.empty?
+
+      Prepared.new(name_version: locked.name_version, require_paths: paths, files: files, rewrites: rewrites)
+    end
+
+    # The stand-ins a fetched ruby_wasm_ic_minimal carries: the libraries it
+    # stands in for, so the locked gems of those names are skipped.
+    def standins(locked)
+      package = ::Gem::Package.new(fetch(locked))
+      Dir.mktmpdir do |dir|
+        package.extract_files(dir, "lib/ruby_wasm_ic_minimal/standins/*.rb")
+        Dir.children(File.join(dir, "lib/ruby_wasm_ic_minimal/standins")).map { File.basename(_1, ".rb") }
+           .reject { _1 == "encoding_constants" }.sort
+      end
+    rescue Errno::ENOENT
+      []
+    end
+
+    private
+
+    def fetch(locked)
+      FileUtils.mkdir_p(@cache)
+      path = File.join(@cache, "#{locked.name_version}.gem")
+      return path if File.file?(path)
+
+      Dir.mktmpdir do |dir|
+        @fetcher.call(locked.name, locked.version, dir)
+        got = File.join(dir, "#{locked.name_version}.gem")
+        raise Refused, "fetching #{locked.name_version} left no #{File.basename(got)}" unless File.file?(got)
+
+        FileUtils.mv(got, path)
+      end
+      path
+    end
+
+    def gem_fetch(name, version, dir)
+      out, status = Open3.capture2e("gem", "fetch", name, "--version", version, "--platform", "ruby", chdir: dir)
+      raise Refused, "gem fetch #{name} #{version} failed:\n#{out}" unless status.success?
+    end
+
+    def check_sum!(locked, path)
+      return unless locked.sha256
+
+      have = Digest::SHA256.file(path).hexdigest
+      return if have == locked.sha256
+
+      raise Refused, "#{locked.name_version}.gem has sha256 #{have}, and the lock says #{locked.sha256}"
+    end
+
+    def check_spec!(locked, spec)
+      unless spec.platform.to_s == "ruby"
+        raise Refused, "#{locked.name_version} was fetched for #{spec.platform}, not ruby: only pure-Ruby gems " \
+                       "can be installed into a canister"
+      end
+      return if spec.extensions.empty?
+
+      raise Refused, "#{locked.name_version} has a C extension (#{spec.extensions.join(', ')}): only pure-Ruby " \
+                     "gems can be installed into a canister, which cannot load compiled code"
+    end
+
+    def read_files(locked, package, spec)
+      files = {}
+      rewrites = []
+      Dir.mktmpdir do |dir|
+        # extract_files matches without FNM_PATHNAME, so "*" crosses "/":
+        # "lib/*" is every file at every depth under lib/ ("lib/**/*" would
+        # miss lib/rack.rb itself).
+        spec.require_paths.each { |rp| package.extract_files(dir, "#{rp}/*") }
+        spec.require_paths.each do |rp|
+          base = File.join(dir, rp)
+          next unless File.directory?(base)
+
+          Dir.glob("**/*", File::FNM_DOTMATCH, base: base).sort.each do |rel|
+            full = File.join(base, rel)
+            next unless File.file?(full)
+
+            body = File.binread(full)
+            path = "#{rp}/#{rel}"
+            if rel.end_with?(".rb")
+              body, rewrite = MagicComment.fix("#{locked.name_version}/#{path}", body)
+              rewrites << rewrite if rewrite
+            end
+            files[path] = body
+          end
+        end
+      end
+      [files, rewrites]
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/installer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubyWasmIcInstaller
+  # The off-chain half's three acts against one canister, through a Runner:
+  # `install` (the lock's gems the canister lacks, then the setup file),
+  # `status` (what installed() says) and `prune` (every version neither the
+  # running boot nor the pending setup names). Each returns the lines of its
+  # report; nothing here prints.
+  class Installer
+    MINIMAL = "ruby_wasm_ic_minimal"
+
+    def initialize(runner:, gem_files:, budget: Plan::DEFAULT_BUDGET)
+      @runner = runner
+      @gem_files = gem_files
+      @budget = budget
+    end
+
+    def status
+      i = installed
+      [
+        "running generation: #{i[:running] || 'none'}",
+        "pending generation: #{i[:pending] || 'none'}#{pending_note(i)}",
+        "installed: #{i[:gems].empty? ? 'none' : i[:gems].join(', ')}",
+        *(i[:partial].empty? ? [] : ["half-sent (.partial): #{i[:partial].join(', ')}"])
+      ]
+    end
+
+    # `dry_run`: plan and report, call nothing that writes.
+    def install(lockfile, dry_run: false)
+      report = []
+      locked = lockfile.gems
+      skip = standins(locked)
+      skipped, wanted = locked.partition { skip.include?(_1.name) }
+      skipped.each { report << "skip #{_1.name_version}: #{MINIMAL} stands in for #{_1.name} on a minimal canister" }
+      prepared = wanted.map { @gem_files.prepare(_1) }
+      prepared.flat_map(&:rewrites).each do |r|
+        report << "rewrite #{r.file}:#{r.line}: magic comment #{r.from} -> #{r.to}"
+      end
+
+      plan = Plan.new(prepared, installed, budget: @budget)
+      plan.sent.each { report << "send #{_1.name_version} (#{_1.files.size} files, #{_1.bytes} bytes)" }
+      if plan.empty?
+        report << "nothing to send: the canister has every locked gem and the setup file already names them"
+        return report
+      end
+
+      plan.steps.each do |step|
+        report << "#{dry_run ? 'would call' : 'call'} #{step.method}: #{step.note}"
+        next if dry_run
+
+        reply = Candid.decode(@runner.call(step.method, step.args)).first
+        report << "  #{reply}"
+      end
+      report << (plan.generation ? "setup generation #{plan.generation} takes effect at the next upgrade" \
+                                 : "the setup file is unchanged")
+      report << "upgrade the canister to load it (icp deploy --mode upgrade)" if plan.generation && !dry_run
+      report
+    end
+
+    def prune(dry_run: false)
+      i = installed
+      keep = (names_of(i[:load_paths]) + names_of(i[:running_paths])).uniq
+      gone = i[:gems] - keep
+      return ["nothing to prune: every installed version is named by the running or pending setup"] if gone.empty?
+
+      gone.map do |nv|
+        next "would remove #{nv}" if dry_run
+
+        reply = Candid.decode(@runner.call("install_remove", Candid.text_arg(nv))).first
+        "remove #{nv}: #{reply}"
+      end
+    end
+
+    private
+
+    def installed
+      v = Candid.decode(@runner.call("installed", Candid.empty_args, query: true)).first
+      Candid.record(v, :running, :pending, :gems, :partial, :load_paths, :running_paths)
+    end
+
+    def names_of(paths) = paths.map { _1.split("/").first }.uniq
+
+    def pending_note(i)
+      return "" if i[:pending].nil? || i[:pending] == i[:running]
+
+      " (takes effect at the next upgrade)"
+    end
+
+    def standins(locked)
+      minimal = locked.find { _1.name == MINIMAL }
+      minimal ? @gem_files.standins(minimal) : []
+    end
+  end
+end

data/lib/ruby_wasm_ic_installer/lockfile.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "bundler"
+
+module RubyWasmIcInstaller
+  class Error < StandardError; end
+
+  # An Application's Gemfile.lock, read with Bundler's own parser (W29, Q8):
+  # each locked gem as a name and version, in the lock's order, with the
+  # sha256 the lock's CHECKSUMS section gives for its `ruby` platform, if any.
+  # Nothing is resolved or installed: the lock is the author's decision.
+  class Lockfile
+    Gem = Struct.new(:name, :version, :sha256, keyword_init: true) do
+      def name_version = "#{name}-#{version}"
+    end
+
+    attr_reader :gems
+
+    def self.read(path)
+      raise Error, "no lockfile at #{path}: run `bundle lock` first" unless File.file?(path)
+
+      new(File.read(path), path: path)
+    end
+
+    def initialize(text, path: "Gemfile.lock")
+      @path = path
+      parser = Bundler::LockfileParser.new(text)
+      @gems = to_gems(parser.specs, checksums(text))
+    end
+
+    private
+
+    # One entry per name: its `ruby` platform spec. A gem locked only for a
+    # native platform cannot be installed, which pure Ruby only means.
+    def to_gems(specs, sums)
+      by_name = specs.group_by(&:name)
+      by_name.map do |name, list|
+        spec = list.find { |s| s.platform.to_s == "ruby" }
+        unless spec
+          raise Error, "#{name} is locked only for #{list.map { _1.platform.to_s }.uniq.join(', ')} in #{@path}: " \
+                       "only pure-Ruby gems can be installed into a canister " \
+                       "(run `bundle lock --add-platform ruby`, or drop the gem)"
+        end
+        source = spec.source
+        unless source.is_a?(Bundler::Source::Rubygems)
+          raise Error, "#{name} comes from #{source.class.name.split('::').last.downcase} in #{@path}: " \
+                       "only gems from a gem server can be installed"
+        end
+        Gem.new(name: name, version: spec.version.to_s, sha256: sums["#{name}-#{spec.version}"])
+      end
+    end
+
+    # The CHECKSUMS section's `ruby`-platform sha256 for each name-version.
+    def checksums(text)
+      section = text[/^CHECKSUMS\n(.*?)(?:\n\S|\z)/m, 1].to_s
+      section.lines.each_with_object({}) do |line, h|
+        next unless (m = line.match(/\A\s+(\S+) \(([^)\s]+)\) sha256=([0-9a-f]{64})/))
+
+        h["#{m[1]}-#{m[2]}"] = m[3]
+      end
+    end
+  end
+end