schepherd 0.1.0

data/bin/schepherd

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/schepherd"
+
+begin
+  binary = Schepherd.executable
+  # The [command, argv0] form never goes through a shell, which a single
+  # string would when schepherd runs without arguments.
+  exec([binary, binary], *ARGV)
+rescue Schepherd::Error => e
+  warn e.message
+  exit 1
+rescue SystemCallError => e
+  warn "schepherd: cannot start #{binary}: #{e.message}"
+  exit 1
+end

data/lib/schepherd.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+# Schepherd delivers pinned JSON Schemas from an OCI catalog to verified local
+# files. This gem ships the native schepherd binary of every supported
+# platform under libexec/; the schepherd executable runs the one built for the
+# running system.
+module Schepherd
+  # Names the environment variable that holds the absolute path of a
+  # schepherd binary to run instead of the bundled one, for systems without a
+  # prebuilt binary.
+  BINARY_OVERRIDE = "SCHEPHERD_BINARY"
+
+  # The os-cpu pairs of libexec/schepherd-<os>-<cpu>. The same table exists in
+  # tools/release/internal/wrappers, which packs the gem; a Go test keeps the two
+  # identical.
+  TARGETS = [
+    %w[darwin arm64],
+    %w[darwin x64],
+    %w[linux arm64],
+    %w[linux x64],
+    %w[windows arm64],
+    %w[windows x64],
+  ].freeze
+
+  # Raised when there is no binary to run.
+  class Error < StandardError; end
+
+  module_function
+
+  # Returns the absolute path of the binary to run: the SCHEPHERD_BINARY
+  # override, or the bundled binary of the platform.
+  def executable(env: ENV, platform: Gem::Platform.local, host: RbConfig::CONFIG,
+                 root: File.expand_path("..", __dir__))
+    override = binary_override(env)
+    return override if override
+
+    pair = target(platform, host)
+    raise Error, unsupported_message(platform) unless TARGETS.include?(pair)
+
+    os, cpu = pair
+    path = File.join(root, "libexec", "schepherd-#{os}-#{cpu}", os == "windows" ? "schepherd.exe" : "schepherd")
+    return path if File.file?(path)
+
+    raise Error, "schepherd: the binary #{path} for #{os}-#{cpu} is missing from the gem. " \
+                 "Reinstall it with `gem install schepherd`, or set #{BINARY_OVERRIDE} to the absolute path " \
+                 "of a schepherd binary."
+  end
+
+  # Returns the [os, cpu] pair of the bundled binary for a platform, or nil.
+  # JRuby reports the platform universal-java, so the host OS and CPU of
+  # RbConfig answer what Gem::Platform cannot.
+  def target(platform = Gem::Platform.local, host = RbConfig::CONFIG)
+    os = os_name(platform.os) || os_name(host["host_os"])
+    cpu = cpu_name(platform.cpu) || cpu_name(host["host_cpu"])
+    [os, cpu] if os && cpu
+  end
+
+  def os_name(os)
+    case os.to_s
+    when /\Alinux/ then "linux"
+    when /\Adarwin/ then "darwin"
+    when /\A(?:mingw|mswin|windows)/ then "windows"
+    end
+  end
+
+  # Apple silicon Rubies may report arm64e, and the system Ruby of macOS a
+  # universal.<cpu> CPU.
+  def cpu_name(cpu)
+    case cpu.to_s.sub(/\Auniversal\./, "")
+    when /\Aarm64/, "aarch64" then "arm64"
+    when "x86_64", "x64", "amd64" then "x64"
+    end
+  end
+
+  # Returns the validated SCHEPHERD_BINARY path, or nil when it is unset or
+  # empty.
+  def binary_override(env = ENV)
+    value = env[BINARY_OVERRIDE]
+    return nil if value.nil? || value.empty?
+
+    unless File.absolute_path?(value)
+      raise Error, "schepherd: #{BINARY_OVERRIDE} must be an absolute path to the schepherd binary, got #{value.inspect}"
+    end
+    return value if File.file?(value)
+
+    raise Error, "schepherd: #{BINARY_OVERRIDE} points to #{value.inspect}, which is not a regular file"
+  end
+
+  def unsupported_message(platform)
+    supported = TARGETS.map { |os, cpu| "#{os}-#{cpu}" }.join(", ")
+    "schepherd: no prebuilt binary for #{platform}. Supported platforms: #{supported}. " \
+      "Set #{BINARY_OVERRIDE} to the absolute path of a schepherd binary built for this system."
+  end
+  private_class_method :unsupported_message
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: schepherd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ovineko
+bindir: bin
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies: []
+description: Schepherd resolves a JSON Schema from a pinned OCI catalog, verifies
+  it by digest and hands the local file to the validator you already use. The gem
+  ships the native schepherd binary for Linux, macOS and Windows on x64 and arm64.
+executables:
+- schepherd
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- THIRD_PARTY_LICENSES.txt
+- bin/schepherd
+- lib/schepherd.rb
+- libexec/schepherd-darwin-arm64/schepherd
+- libexec/schepherd-darwin-x64/schepherd
+- libexec/schepherd-linux-arm64/schepherd
+- libexec/schepherd-linux-x64/schepherd
+- libexec/schepherd-windows-arm64/schepherd.exe
+- libexec/schepherd-windows-x64/schepherd.exe
+homepage: https://schepherd.ovineko.com
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/ovineko/schepherd/issues
+  changelog_uri: https://github.com/ovineko/schepherd/releases
+  documentation_uri: https://schepherd.ovineko.com
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/ovineko/schepherd
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Delivers pinned JSON Schemas from an OCI catalog to verified local files
+test_files: []