fhir_packages_manager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c3db88fe718417bdd2a0bd82604b48928db13d036ee912094cb8891e5218d967
+  data.tar.gz: d84a0f807bcd2f479cd511fb100cfd9c723c6b59fca65c5dc41aa2e6dd829418
+SHA512:
+  metadata.gz: 17d1da3f230507fbeb91cd949a90370561bcdeece97bdf433b169f16b7baadf960cc542bd9931f56b2b6afe93936a1d53865efe8f45e9be969e2f1883dcb5acf
+  data.tar.gz: 3b4e62d57b1b034c137869355e2d8454fc92292d3b0b59f4825abc89af0d86013afd76f563de14f95a23a03e28f1fd7783ef8b54994e7cf5137d44068bda562e

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-10
+
+### Added
+
+- **Library**: `FhirPackagesManager::Manager`, `Registry`, `Package`, `IgnoreList`, and
+  `FetchResult`, providing:
+  - Availability checks and version resolution (including `latest`) against one or more
+    npm-style FHIR package registries (e.g. `packages.fhir.org`, `packages.simplifier.net`),
+    tried in the order given.
+  - A configurable ignore list (loaded from YAML or JSON) that skips a package entirely or
+    pins a single ignored version.
+  - Tarball download into a destination folder, with `HttpError`/`PackageNotFoundError` for
+    failure cases and a `:downloaded`/`:ignored`/`:not_found`/`:error` result per package.
+- **CLI**: `fhir_packages_manager` executable with `check` and `fetch` subcommands
+  (`-r/--registry`, `-d/--destination`, `-i/--ignore-file`, repeatable `--registry`).
+- **Docker**: a multi-stage `Dockerfile` that builds and installs the gem from source and
+  exposes the CLI as the image's entrypoint, plus a `docker-compose.yml` for running it
+  without a local Ruby install.
+- **Tests**: an RSpec suite (HTTP stubbed with WebMock, so it never hits a real registry)
+  covering the library, CLI, and every registry edge case (redirects, missing `Location`
+  header, unsupported URL schemes, 404s, etc.), with 100% line and branch coverage enforced
+  by a SimpleCov minimum-coverage gate.
+- **Code quality tooling**: RuboCop, Reek, Fasterer, Flay, Flog, and Steep (with full RBS
+  signatures for every class), all wired into `bundle exec rake`.
+- **CI/CD** (GitHub Actions):
+  - `quality.yml` — runs the full test/quality suite on every push to any branch, uploading
+    coverage to Codecov.
+  - `release.yml` — on a published GitHub Release or manual dispatch, re-runs the test/quality
+    gate, then publishes the gem to RubyGems.org (via Trusted Publishing) and the Docker image
+    to GitHub Container Registry.
+  - `docs.yml` — publishes YARD API documentation to GitHub Pages on every push to `main`.
+- **Documentation**: YARD doc comments across the public API, and a Codecov/docs badge pair
+  in the README.
+
+[Unreleased]: https://github.com/projkov/fhir_packages_manager/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/projkov/fhir_packages_manager/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"fhir_packages_manager" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["prozskov@gmail.com"](mailto:"prozskov@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Pavel Rozhkov
+
+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,157 @@
+# FhirPackagesManager
+
+[![codecov](https://codecov.io/gh/projkov/fhir_packages_manager/graph/badge.svg)](https://codecov.io/gh/projkov/fhir_packages_manager)
+[![docs](https://img.shields.io/badge/docs-yard-blue.svg)](https://projkov.github.io/fhir_packages_manager/)
+
+Checks the availability of FHIR implementation guide packages against npm-style
+registries (e.g. `packages.fhir.org`, `packages.simplifier.net`), skips any
+packages/versions on a configurable ignore list, and downloads the resulting
+`.tgz` tarballs into a destination folder.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add fhir_packages_manager
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install fhir_packages_manager
+```
+
+## Usage
+
+### Library
+
+```ruby
+require "fhir_packages_manager"
+
+manager = FhirPackagesManager::Manager.new(
+  registries: ["https://packages.fhir.org", "https://packages.simplifier.net"],
+  destination: "./fhir_packages",
+  ignore_list: FhirPackagesManager::IgnoreList.load("fhir_packages_ignore.yml") # optional
+)
+
+manager.available?("hl7.fhir.us.core", "6.1.0") # => true/false
+
+result = manager.fetch("hl7.fhir.us.core@6.1.0")
+result.status # => :downloaded, :ignored, :not_found, or :error
+result.path   # => "./fhir_packages/hl7.fhir.us.core-6.1.0.tgz" when downloaded
+
+manager.fetch_all(["hl7.fhir.us.core@6.1.0", "hl7.fhir.r4.core"]) # bare name = latest
+```
+
+The ignore list file (YAML or JSON) is a flat array where a bare string
+ignores every version of a package, and a hash pins a single version:
+
+```yaml
+- hl7.fhir.r4.core
+- name: hl7.fhir.us.core
+  version: 3.1.0
+```
+
+### CLI
+
+```bash
+exe/fhir_packages_manager check hl7.fhir.us.core@6.1.0 -r https://packages.fhir.org
+exe/fhir_packages_manager fetch hl7.fhir.us.core@6.1.0 hl7.fhir.r4.core \
+  -r https://packages.fhir.org -r https://packages.simplifier.net \
+  -d ./fhir_packages -i fhir_packages_ignore.yml
+```
+
+### Docker
+
+The CLI is also published as a container image, so it can be used without installing Ruby
+or the gem locally:
+
+```bash
+docker run --rm ghcr.io/projkov/fhir_packages_manager check hl7.fhir.us.core@6.1.0 -r https://packages.fhir.org
+
+docker run --rm -v "$(pwd)/fhir_packages:/fhir_packages" ghcr.io/projkov/fhir_packages_manager \
+  fetch hl7.fhir.us.core@6.1.0 -r https://packages.fhir.org -d /fhir_packages
+```
+
+Mount a volume (as above) to get downloaded `.tgz` files back out onto the host.
+
+#### Docker Compose
+
+A `docker-compose.yml` is included so the image name and volume mount don't need to be
+retyped for every invocation:
+
+```yaml
+services:
+  fhir_packages_manager:
+    image: ghcr.io/projkov/fhir_packages_manager:latest
+    build: .
+    volumes:
+      - ./fhir_packages:/fhir_packages
+      # - ./fhir_packages_ignore.yml:/fhir_packages_ignore.yml:ro
+```
+
+Since the image's `ENTRYPOINT` is the CLI itself, anything passed after the service name
+becomes its arguments:
+
+```bash
+docker compose run --rm fhir_packages_manager \
+  check hl7.fhir.us.core@6.1.0 -r https://packages.fhir.org
+
+docker compose run --rm fhir_packages_manager \
+  fetch hl7.fhir.us.core@6.1.0 -r https://packages.fhir.org -d /fhir_packages
+```
+
+`docker compose run --rm` (rather than `up`) is used because this is a one-shot CLI, not a
+long-running service — `--rm` discards the container after it exits. `docker compose pull`
+fetches the published image from GHCR; `docker compose build` builds it locally from the
+`Dockerfile` instead (e.g. to test an unreleased change). Uncomment the ignore-file volume
+line and add `-i /fhir_packages_ignore.yml` to the command to use an ignore list.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version: bump `VERSION` in `lib/fhir_packages_manager/version.rb`, add a
+dated entry to `CHANGELOG.md`, and merge to `main`. Then either publish a GitHub Release (tag
+`vX.Y.Z`) or manually run the `Release` workflow from the Actions tab — `.github/workflows/release.yml`
+re-runs the full test/quality gate and, if it passes, publishes the gem to
+[rubygems.org](https://rubygems.org) via Trusted Publishing and pushes the Docker image to
+GHCR. Don't run `bundle exec rake release` locally — it would try to push using local
+credentials instead of through that pipeline.
+
+### Tests and code quality
+
+`bundle exec rake` runs the full suite: RSpec (with a SimpleCov gate requiring 95%+ line
+coverage), RuboCop, Reek, Fasterer, Flay, Flog, and Steep. Each is also runnable on its own,
+e.g. `bundle exec rspec`, `bundle exec rake rubocop`, `bundle exec rake steep`.
+
+RSpec specs stub all HTTP calls with WebMock (see `spec/fhir_packages_manager/registry_spec.rb`
+and `cli_spec.rb`), so the suite never hits a real registry.
+
+### Documentation
+
+API docs are generated from the code with [YARD](https://yardoc.org) and published to
+[GitHub Pages](https://projkov.github.io/fhir_packages_manager/) by
+`.github/workflows/docs.yml` on every push to `main`. To build and browse them locally:
+
+```bash
+bundle exec yard doc   # writes HTML to doc/
+bundle exec yard server --reload  # serves it at http://localhost:8808, rebuilding on change
+```
+
+`bundle exec yard stats --list-undoc` lists any undocumented public classes/methods.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/projkov/fhir_packages_manager. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/projkov/fhir_packages_manager/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the FhirPackagesManager project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/projkov/fhir_packages_manager/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+require 'reek/rake/task'
+Reek::Rake::Task.new do |t|
+  t.source_files = '{lib,exe}/**/*.rb'
+end
+
+require 'flay_task'
+FlayTask.new(:flay, 200, %w[lib exe])
+
+require 'flog_task'
+FlogTask.new(:flog, 30, %w[lib exe], :max_method)
+
+desc 'Check for slow Ruby idioms with fasterer'
+task :fasterer do
+  sh 'bundle exec fasterer lib exe'
+end
+
+desc 'Type-check with Steep'
+task :steep do
+  sh 'bundle exec steep check'
+end
+
+task default: %i[spec rubocop reek fasterer flay flog steep]

data/exe/fhir_packages_manager

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fhir_packages_manager'
+require 'fhir_packages_manager/cli'
+
+FhirPackagesManager::CLI.run(ARGV)

data/lib/fhir_packages_manager/cli.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module FhirPackagesManager
+  # Command-line entry point backing the `fhir_packages_manager` executable.
+  # See the "CLI" section of the README for usage examples.
+  class CLI
+    # @return [Array<String>] the supported subcommands
+    COMMANDS = %w[fetch check].freeze
+
+    # @return [String] usage text shown on --help and on invalid invocations
+    BANNER = <<~USAGE
+      Usage: fhir_packages_manager COMMAND package[@version] [package[@version] ...] [options]
+
+      Commands:
+        fetch   Download packages into the destination folder
+        check   Report which registry (if any) has each package/version
+
+    USAGE
+
+    # Parses argv and runs the requested command (`fetch` or `check`).
+    #
+    # @param argv [Array<String>] arguments as passed to the executable, e.g. ARGV
+    # @return [void]
+    def self.run(argv)
+      new(argv).run
+    end
+
+    # @param argv [Array<String>] see {.run}
+    def initialize(argv)
+      @argv = argv.dup
+      @options = { destination: './fhir_packages', registries: [] } # : Hash[Symbol, untyped]
+    end
+
+    # @return [void]
+    def run
+      parser.parse!(@argv)
+      command = @argv.shift
+      package_specs = @argv
+
+      return usage_error(1) if !COMMANDS.include?(command) || package_specs.empty?
+      return usage_error('Error: at least one --registry URL is required') if @options[:registries].empty?
+
+      dispatch(command, package_specs)
+    end
+
+    private
+
+    def dispatch(command, package_specs)
+      case command
+      when 'fetch'
+        fetch(package_specs)
+      when 'check'
+        check(package_specs)
+      end
+    end
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = BANNER
+        define_options(opts)
+      end
+    end
+
+    def define_options(opts)
+      opts.on('-r URL', '--registry URL', 'Registry base URL (repeatable, checked in order given)') do |value|
+        @options[:registries] << value
+      end
+      opts.on('-d DIR', '--destination DIR',
+              'Destination folder for downloaded packages (default: ./fhir_packages)') do |value|
+        @options[:destination] = value
+      end
+      opts.on('-i PATH', '--ignore-file PATH', 'YAML/JSON file listing packages/versions to ignore') do |value|
+        @options[:ignore_file] = value
+      end
+      opts.on('-h', '--help', 'Show this help') do
+        puts opts
+        exit
+      end
+    end
+
+    def usage_error(message_or_status)
+      if message_or_status.is_a?(String)
+        warn message_or_status
+      else
+        warn parser
+      end
+      exit 1
+    end
+
+    def manager
+      @manager ||= Manager.new(
+        registries: @options[:registries],
+        destination: @options[:destination],
+        ignore_list: load_ignore_list
+      )
+    end
+
+    def load_ignore_list
+      ignore_file = @options[:ignore_file]
+      IgnoreList.load(ignore_file) if ignore_file
+    end
+
+    def fetch(package_specs)
+      results = manager.fetch_all(package_specs)
+      results.each { |result| puts fetch_line(result) }
+      exit 1 if results.any? { |result| result.not_found? || result.error? }
+    end
+
+    def fetch_line(result)
+      package = result.package
+      case result.status
+      when :downloaded then "OK    #{package} -> #{result.path} (#{result.registry})"
+      when :ignored then "SKIP  #{package} (ignored)"
+      when :not_found then "MISS  #{package} (not found in any registry)"
+      when :error then "ERR   #{package}: #{result.error}"
+      end
+    end
+
+    def check(package_specs)
+      package_specs.each do |spec|
+        package = Package.parse(spec)
+        found = manager.find_registry(package.name, package.version)
+        puts check_line(package, found)
+      end
+    end
+
+    def check_line(package, found)
+      return "UNAVAILABLE #{package}" unless found
+
+      registry, version = found
+      "AVAILABLE   #{package.name}@#{version} (#{registry.base_url})"
+    end
+  end
+end

data/lib/fhir_packages_manager/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FhirPackagesManager
+  # Base class for all errors raised by this gem.
+  class Error < StandardError; end
+
+  # Raised for any non-2xx/3xx HTTP response from a registry.
+  class HttpError < Error
+    # @return [Integer, nil] the HTTP status code, or nil for a connection-level failure
+    attr_reader :status
+
+    # @param message [String]
+    # @param status [Integer, nil]
+    def initialize(message, status)
+      super(message)
+      @status = status
+    end
+  end
+
+  # Raised when a package or version does not exist on a registry.
+  class PackageNotFoundError < Error; end
+end

data/lib/fhir_packages_manager/fetch_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FhirPackagesManager
+  # Outcome of {Manager#fetch} for a single package.
+  #
+  # @!attribute package
+  #   @return [Package] the package that was requested (version resolved, when downloaded)
+  # @!attribute status
+  #   @return [Symbol] one of :downloaded, :ignored, :not_found, :error
+  # @!attribute registry
+  #   @return [String, nil] the base URL of the registry that served the package, if downloaded
+  # @!attribute path
+  #   @return [String, nil] where the tarball was written, if downloaded
+  # @!attribute error
+  #   @return [String, nil] the error message, when status is :error
+  class FetchResult < Struct.new(:package, :status, :registry, :path, :error, keyword_init: true)
+    # @return [Boolean] true if the package was downloaded successfully
+    def downloaded?
+      status == :downloaded
+    end
+
+    # @return [Boolean] true if the package was skipped because it's on the ignore list
+    def ignored?
+      status == :ignored
+    end
+
+    # @return [Boolean] true if no registry had the package/version
+    def not_found?
+      status == :not_found
+    end
+
+    # @return [Boolean] true if downloading raised an HTTP error
+    def error?
+      status == :error
+    end
+  end
+end

data/lib/fhir_packages_manager/ignore_list.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+
+module FhirPackagesManager
+  # A list of packages (optionally pinned to a version) to skip when fetching.
+  #
+  # Loaded from a YAML or JSON file containing a flat array, e.g.:
+  #
+  #   - hl7.fhir.r4.core           # ignore every version of this package
+  #   - name: hl7.fhir.us.core
+  #     version: 3.1.0             # ignore only this one version
+  class IgnoreList
+    # Loads an ignore list from a YAML or JSON file (JSON iff the extension is .json).
+    #
+    # @param path [String] path to a YAML or JSON file containing a flat array of entries
+    # @return [IgnoreList]
+    def self.load(path)
+      data = case File.extname(path).downcase
+             when '.json'
+               JSON.parse(File.read(path))
+             else
+               YAML.load_file(path)
+             end
+      new(data || [])
+    end
+
+    # @param entries [Array<String, Hash>] bare package names (ignore every version) and/or
+    #   `{"name" => ..., "version" => ...}` hashes (ignore only that version)
+    # @raise [ArgumentError] if an entry is neither a String nor a Hash
+    def initialize(entries = [])
+      @entries = entries.map { |entry| normalize(entry) }
+    end
+
+    # @param name [String] the package name
+    # @param version [String, nil] the version being requested, if any
+    # @return [Boolean] true if this name/version is on the ignore list
+    def ignored?(name, version = nil)
+      @entries.any? { |entry| matches?(entry, name, version) }
+    end
+
+    private
+
+    def matches?(entry, name, version)
+      return false unless entry[:name] == name
+
+      ignored_version = entry[:version]
+      ignored_version.nil? || ignored_version == version
+    end
+
+    def normalize(entry)
+      case entry
+      when String
+        { name: entry, version: nil }
+      when Hash
+        normalize_hash(entry)
+      else
+        raise ArgumentError, "Invalid ignore list entry: #{entry.inspect}"
+      end
+    end
+
+    def normalize_hash(entry)
+      version = entry['version'] || entry[:version]
+      { name: entry['name'] || entry[:name], version: version&.to_s }
+    end
+  end
+end

data/lib/fhir_packages_manager/manager.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module FhirPackagesManager
+  # Orchestrates checking availability across a set of registries, honoring an
+  # ignore list, and downloading tarballs into a destination folder.
+  class Manager
+    # @return [Array<Registry>] registries checked, in the order given to {#initialize}
+    attr_reader :registries
+    # @return [String] the folder packages are downloaded into
+    attr_reader :destination
+    # @return [IgnoreList, nil] packages/versions skipped by {#fetch}
+    attr_reader :ignore_list
+
+    # @param registries [Array<String, Registry>] one or more registry base URLs and/or
+    #   {Registry} instances, checked in the order given
+    # @param destination [String] folder downloaded tarballs are written into
+    # @param ignore_list [IgnoreList, nil] packages/versions to skip in {#fetch}
+    # @raise [ArgumentError] if registries is nil or empty
+    def initialize(registries:, destination:, ignore_list: nil)
+      raise ArgumentError, 'at least one registry is required' if registries.nil? || registries.empty?
+
+      @registries = registries.map { |entry| entry.is_a?(Registry) ? entry : Registry.new(entry) }
+      @destination = destination.to_s
+      @ignore_list = ignore_list
+    end
+
+    # @param name [String] the package name
+    # @param version [String, nil] a specific version, or nil/"latest" for the newest
+    # @return [Boolean] true if any configured registry has this package/version
+    def available?(name, version = nil)
+      !find_registry(name, version).nil?
+    end
+
+    # @param name [String] the package name
+    # @param version [String, nil] a specific version, or nil/"latest" for the newest
+    # @return [Array(Registry, String), nil] the first registry that has this package/version,
+    #   paired with the resolved version string; nil if none of them do
+    def find_registry(name, version = nil)
+      registries.each do |registry|
+        resolved = registry.version?(name, version)
+        return [registry, resolved] if resolved
+      end
+      nil
+    end
+
+    # Fetches a single package. Skips it if it's on the ignore list, otherwise downloads
+    # its tarball into {#destination}.
+    #
+    # @param package [String, Package] a "name@version" string, a bare name (latest), or a Package
+    # @return [FetchResult]
+    def fetch(package)
+      fetch_package(Package.parse(package))
+    end
+
+    # @param packages [Array<String, Package>] see {#fetch}
+    # @return [Array<FetchResult>] one result per package, in the same order
+    def fetch_all(packages)
+      packages.map { |package| fetch(package) }
+    end
+
+    private
+
+    def fetch_package(package)
+      return FetchResult.new(package: package, status: :ignored) if ignored?(package)
+
+      found = find_registry(package.name, package.version)
+      return FetchResult.new(package: package, status: :not_found) unless found
+
+      download_result(package, found)
+    rescue HttpError => e
+      FetchResult.new(package: package, status: :error, error: e.message)
+    end
+
+    def ignored?(package)
+      !!ignore_list&.ignored?(package.name, package.version)
+    end
+
+    def download_result(package, found)
+      registry, resolved_version = found
+      name = package.name
+      target = File.join(destination, "#{name}-#{resolved_version}.tgz")
+      registry.download(name, resolved_version, target)
+      FetchResult.new(package: Package.new(name, resolved_version), status: :downloaded,
+                      registry: registry.base_url, path: target)
+    end
+  end
+end

data/lib/fhir_packages_manager/package.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FhirPackagesManager
+  # A requested package, e.g. "hl7.fhir.us.core@6.1.0" or "hl7.fhir.us.core"
+  # (version nil/"latest" means "resolve to the registry's latest version").
+  #
+  # @!attribute name
+  #   @return [String] the FHIR package name, e.g. "hl7.fhir.us.core"
+  # @!attribute version
+  #   @return [String, nil] the requested version, or nil/"latest" for the newest available
+  class Package < Struct.new(:name, :version)
+    # Parses a "name@version" (or bare "name") spec string into a Package.
+    #
+    # @param spec [String, Package] a spec string, or an existing Package (returned as-is)
+    # @return [Package]
+    def self.parse(spec)
+      return spec if spec.is_a?(Package)
+
+      parts = spec.to_s.split('@', 2)
+      new(parts[0] || '', parts[1])
+    end
+
+    # @return [String] "name@version", or just "name" when version is nil
+    def to_s
+      version ? "#{name}@#{version}" : name
+    end
+  end
+end

data/lib/fhir_packages_manager/registry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'fileutils'
+
+module FhirPackagesManager
+  # Client for a single FHIR package registry (e.g. https://packages.fhir.org
+  # or https://packages.simplifier.net). Both implement the same npm-style
+  # registry API: `GET /<package>` returns metadata with a "versions" map and
+  # "dist-tags", and `GET /<package>/<version>` streams the .tgz tarball.
+  class Registry
+    # @return [Integer] maximum HTTP redirects followed before raising {HttpError}
+    MAX_REDIRECTS = 5
+
+    # @return [String] the registry's base URL, with any trailing slash stripped
+    attr_reader :base_url
+
+    # @param base_url [String] e.g. "https://packages.fhir.org"
+    def initialize(base_url)
+      @base_url = base_url.to_s.chomp('/')
+      @metadata_cache = {} # : Hash[String, Hash[untyped, untyped]]
+    end
+
+    # Fetches (and caches) the full registry metadata document for a package name.
+    #
+    # @param name [String] the package name
+    # @return [Hash] the parsed npm-style registry metadata ("dist-tags", "versions", etc.)
+    # @raise [PackageNotFoundError] if the package doesn't exist on this registry
+    # @raise [HttpError] for any other non-2xx/3xx response
+    def metadata(name)
+      @metadata_cache[name] ||= JSON.parse(get("#{base_url}/#{name}"))
+    rescue HttpError => e
+      raise PackageNotFoundError, "#{name} not found on #{base_url}" if e.status == 404
+
+      raise
+    end
+
+    # @param name [String] the package name
+    # @param version [String, nil] a specific version, or nil/"latest" for the newest
+    # @return [String, nil] the resolved version string if it exists on this registry,
+    #   or nil if the package or version doesn't exist (never raises)
+    def version?(name, version = nil)
+      meta = metadata(name)
+      resolved = resolve_version(meta, version)
+      resolved && meta['versions']&.key?(resolved) ? resolved : nil
+    rescue PackageNotFoundError
+      nil
+    end
+
+    # @param name [String] the package name
+    # @param version [String] an exact version, as returned by {#version?}
+    # @return [String] the tarball's download URL
+    # @raise [PackageNotFoundError] if the name/version doesn't exist on this registry
+    def tarball_url(name, version)
+      meta = metadata(name)
+      entry = meta.dig('versions', version)
+      raise PackageNotFoundError, "#{name}@#{version} not found on #{base_url}" unless entry
+
+      entry.dig('dist', 'tarball') || "#{base_url}/#{name}/#{version}"
+    end
+
+    # Downloads the package tarball to destination_path, creating parent directories as needed.
+    #
+    # @param name [String] the package name
+    # @param version [String] an exact version, as returned by {#version?}
+    # @param destination_path [String] where to write the downloaded .tgz file
+    # @return [String] destination_path
+    # @raise [PackageNotFoundError] if the name/version doesn't exist on this registry
+    # @raise [HttpError] if the download itself fails
+    def download(name, version, destination_path)
+      FileUtils.mkdir_p(File.dirname(destination_path))
+      download_file(tarball_url(name, version), destination_path)
+      destination_path
+    end
+
+    private
+
+    def resolve_version(meta, version)
+      return meta.dig('dist-tags', 'latest') if version.nil? || version == 'latest'
+
+      version
+    end
+
+    def get(url)
+      request(url, read_timeout: 30) { |http, uri| http.get(uri.request_uri, 'Accept' => 'application/json') }.body
+    end
+
+    def download_file(url, destination_path)
+      request(url, read_timeout: 120) do |http, uri|
+        http.request_get(uri.request_uri) do |response|
+          save_body(response, destination_path) if response.is_a?(Net::HTTPSuccess)
+        end
+      end
+    end
+
+    def save_body(response, destination_path)
+      File.open(destination_path, 'wb') do |file|
+        response.read_body { |chunk| file.write(chunk) }
+      end
+    end
+
+    # Issues a GET, yielding (http, uri) to perform it, and follows any
+    # redirect response by re-issuing the same block against the new location.
+    def request(url, read_timeout:, redirects_left: MAX_REDIRECTS, &)
+      raise HttpError.new("Too many redirects for #{url}", nil) if redirects_left <= 0
+
+      uri = URI(url)
+      raise HttpError.new("Unsupported URL scheme: #{url}", nil) unless uri.is_a?(URI::HTTP)
+
+      host = uri.host or raise HttpError.new("URL has no host: #{url}", nil)
+
+      response = Net::HTTP.start(host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 10,
+                                                 read_timeout: read_timeout) do |http|
+        yield http, uri
+      end
+
+      follow(response, url, read_timeout:, redirects_left:, &)
+    end
+
+    def follow(response, url, read_timeout:, redirects_left:, &)
+      case response
+      when Net::HTTPSuccess
+        response
+      when Net::HTTPRedirection
+        location = response['location'] or raise HttpError.new("Redirect from #{url} has no Location header", nil)
+
+        request(location, read_timeout:, redirects_left: redirects_left - 1, &)
+      else
+        status = response.code.to_i
+        raise HttpError.new("GET #{url} failed: #{status} #{response.message}", status)
+      end
+    end
+  end
+end

data/lib/fhir_packages_manager/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FhirPackagesManager
+  # @return [String] the gem's version, following semver
+  VERSION = '0.1.0'
+end

data/lib/fhir_packages_manager.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'fhir_packages_manager/version'
+require_relative 'fhir_packages_manager/errors'
+require_relative 'fhir_packages_manager/package'
+require_relative 'fhir_packages_manager/fetch_result'
+require_relative 'fhir_packages_manager/registry'
+require_relative 'fhir_packages_manager/ignore_list'
+require_relative 'fhir_packages_manager/manager'
+
+# Checks the availability of FHIR implementation guide packages against
+# npm-style registries (e.g. packages.fhir.org, packages.simplifier.net),
+# skips entries on a configurable {IgnoreList}, and downloads the resulting
+# tarballs via {Manager}. See the README for usage examples.
+module FhirPackagesManager
+end

data/sig/fhir_packages_manager/cli.rbs

@@ -0,0 +1,34 @@
+module FhirPackagesManager
+  class CLI
+    COMMANDS: Array[String]
+    BANNER: String
+
+    def self.run: (Array[String] argv) -> void
+
+    def initialize: (Array[String] argv) -> void
+
+    def run: () -> void
+
+    private
+
+    def dispatch: (String? command, Array[String] package_specs) -> void
+
+    def parser: () -> OptionParser
+
+    def define_options: (OptionParser opts) -> void
+
+    def usage_error: (String | Integer message_or_status) -> bot
+
+    def manager: () -> Manager
+
+    def load_ignore_list: () -> IgnoreList?
+
+    def fetch: (Array[String] package_specs) -> void
+
+    def fetch_line: (FetchResult result) -> String?
+
+    def check: (Array[String] package_specs) -> void
+
+    def check_line: (Package package, [Registry, String]? found) -> String
+  end
+end

data/sig/fhir_packages_manager/errors.rbs

@@ -0,0 +1,13 @@
+module FhirPackagesManager
+  class Error < StandardError
+  end
+
+  class HttpError < Error
+    attr_reader status: Integer?
+
+    def initialize: (String message, Integer? status) -> void
+  end
+
+  class PackageNotFoundError < Error
+  end
+end

data/sig/fhir_packages_manager/fetch_result.rbs

@@ -0,0 +1,19 @@
+module FhirPackagesManager
+  class FetchResult < Struct[untyped]
+    attr_accessor package: Package
+    attr_accessor status: Symbol
+    attr_accessor registry: String?
+    attr_accessor path: String?
+    attr_accessor error: String?
+
+    def self.new: (package: Package, status: Symbol, ?registry: String?, ?path: String?, ?error: String?) -> FetchResult
+
+    def downloaded?: () -> bool
+
+    def ignored?: () -> bool
+
+    def not_found?: () -> bool
+
+    def error?: () -> bool
+  end
+end

data/sig/fhir_packages_manager/ignore_list.rbs

@@ -0,0 +1,17 @@
+module FhirPackagesManager
+  class IgnoreList
+    def self.load: (String path) -> IgnoreList
+
+    def initialize: (?Array[String | Hash[untyped, untyped]] entries) -> void
+
+    def ignored?: (String name, ?String? version) -> bool
+
+    private
+
+    def matches?: (Hash[Symbol, String?] entry, String name, String? version) -> bool
+
+    def normalize: (String | Hash[untyped, untyped] entry) -> Hash[Symbol, String?]
+
+    def normalize_hash: (Hash[untyped, untyped] entry) -> Hash[Symbol, String?]
+  end
+end

data/sig/fhir_packages_manager/manager.rbs

@@ -0,0 +1,25 @@
+module FhirPackagesManager
+  class Manager
+    attr_reader registries: Array[Registry]
+    attr_reader destination: String
+    attr_reader ignore_list: IgnoreList?
+
+    def initialize: (registries: Array[String | Registry], destination: String, ?ignore_list: IgnoreList?) -> void
+
+    def available?: (String name, ?String? version) -> bool
+
+    def find_registry: (String name, ?String? version) -> [Registry, String]?
+
+    def fetch: (String | Package package) -> FetchResult
+
+    def fetch_all: (Array[String | Package] packages) -> Array[FetchResult]
+
+    private
+
+    def fetch_package: (Package package) -> FetchResult
+
+    def ignored?: (Package package) -> bool
+
+    def download_result: (Package package, [Registry, String] found) -> FetchResult
+  end
+end

data/sig/fhir_packages_manager/package.rbs

@@ -0,0 +1,12 @@
+module FhirPackagesManager
+  class Package < Struct[untyped]
+    attr_accessor name: String
+    attr_accessor version: String?
+
+    def self.new: (String name, ?String? version) -> Package
+
+    def self.parse: (Package | String spec) -> Package
+
+    def to_s: () -> String
+  end
+end

data/sig/fhir_packages_manager/registry.rbs

@@ -0,0 +1,31 @@
+module FhirPackagesManager
+  class Registry
+    MAX_REDIRECTS: Integer
+
+    attr_reader base_url: String
+
+    def initialize: (String base_url) -> void
+
+    def metadata: (String name) -> Hash[untyped, untyped]
+
+    def version?: (String name, ?String? version) -> String?
+
+    def tarball_url: (String name, String version) -> String
+
+    def download: (String name, String version, String destination_path) -> String
+
+    private
+
+    def resolve_version: (Hash[untyped, untyped] meta, String? version) -> String?
+
+    def get: (String url) -> String
+
+    def download_file: (String url, String destination_path) -> void
+
+    def save_body: (Net::HTTPResponse response, String destination_path) -> void
+
+    def request: (String url, read_timeout: Integer, ?redirects_left: Integer) { (Net::HTTP, URI::HTTP) -> untyped } -> Net::HTTPResponse
+
+    def follow: (Net::HTTPResponse response, String url, read_timeout: Integer, redirects_left: Integer) { (Net::HTTP, URI::HTTP) -> untyped } -> Net::HTTPResponse
+  end
+end

data/sig/fhir_packages_manager/version.rbs

@@ -0,0 +1,3 @@
+module FhirPackagesManager
+  VERSION: String
+end

data/sig/fhir_packages_manager.rbs

@@ -0,0 +1,2 @@
+module FhirPackagesManager
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: fhir_packages_manager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pavel Rozhkov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-10 00:00:00.000000000 Z
+dependencies: []
+description: Resolves FHIR implementation guide packages against registries such as
+  packages.fhir.org and packages.simplifier.net, skips entries on a configurable ignore
+  list, and downloads the resulting tarballs into a folder.
+email:
+- prozskov@gmail.com
+- pavel.r@beda.software
+executables:
+- fhir_packages_manager
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/fhir_packages_manager
+- lib/fhir_packages_manager.rb
+- lib/fhir_packages_manager/cli.rb
+- lib/fhir_packages_manager/errors.rb
+- lib/fhir_packages_manager/fetch_result.rb
+- lib/fhir_packages_manager/ignore_list.rb
+- lib/fhir_packages_manager/manager.rb
+- lib/fhir_packages_manager/package.rb
+- lib/fhir_packages_manager/registry.rb
+- lib/fhir_packages_manager/version.rb
+- sig/fhir_packages_manager.rbs
+- sig/fhir_packages_manager/cli.rbs
+- sig/fhir_packages_manager/errors.rbs
+- sig/fhir_packages_manager/fetch_result.rbs
+- sig/fhir_packages_manager/ignore_list.rbs
+- sig/fhir_packages_manager/manager.rbs
+- sig/fhir_packages_manager/package.rbs
+- sig/fhir_packages_manager/registry.rbs
+- sig/fhir_packages_manager/version.rbs
+homepage: https://github.com/projkov/fhir_packages_manager
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/projkov/fhir_packages_manager
+  documentation_uri: https://projkov.github.io/fhir_packages_manager/
+  changelog_uri: https://github.com/projkov/fhir_packages_manager/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Check availability of and download FHIR packages from npm-style registries.
+test_files: []