crosspack 0.2.0

data/lib/crossbuild/version_scheme.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Crossbuild
+  # Computes the build version from the `version:` field of build.yaml.
+  # Supported specs:
+  #   calver    — YYYY.MM.DD-<seconds since local midnight>, e.g. 2026.08.31-33837
+  #   git-tag   — latest `git describe --tags --abbrev=0`, fallback 0.0.0-dev
+  #   env:VAR   — take VAR from the environment (error when unset)
+  #   <other>   — any other non-empty string is used verbatim as a literal
+  # nil/absent defaults to calver.
+  class VersionScheme
+    class Error < StandardError; end
+
+    CALVER = 'calver'.freeze
+    GIT_TAG = 'git-tag'.freeze
+    ENV_PREFIX = 'env:'.freeze
+
+    def initialize(spec)
+      @spec = spec.nil? || spec.to_s.strip.empty? ? CALVER : spec.to_s.strip
+    end
+
+    def compute(root: Dir.pwd, now: Time.now)
+      case @spec
+      when CALVER
+        format('%s-%d', now.strftime('%Y.%m.%d'), now.hour * 3600 + now.min * 60 + now.sec)
+      when GIT_TAG
+        git_tag(root)
+      when /\A#{ENV_PREFIX}(\S+)\z/
+        env_version(Regexp.last_match(1))
+      else
+        @spec
+      end
+    end
+
+    private
+
+    def git_tag(root)
+      tag = Dir.chdir(root) { `git describe --tags --abbrev=0 2>/dev/null`.strip }
+      tag.empty? ? '0.0.0-dev' : tag
+    rescue Errno::ENOENT
+      '0.0.0-dev'
+    end
+
+    def env_version(var)
+      value = ENV[var].to_s.strip
+      raise Error, "version env var #{var} is not set (version: env:#{var} in build.yaml)" if value.empty?
+
+      value
+    end
+  end
+end

data/lib/crossbuild.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Crossbuild
+  class Error < StandardError; end
+end
+
+require_relative 'crosspack'
+
+require_relative 'crossbuild/version'
+require_relative 'crossbuild/platform'
+require_relative 'crossbuild/version_scheme'
+require_relative 'crossbuild/build_manifest'
+require_relative 'crossbuild/runner'
+require_relative 'crossbuild/distributor'
+require_relative 'crossbuild/matrix'
+require_relative 'crossbuild/builder'
+
+module Crossbuild
+  # Convenience wrapper: Crossbuild.build('build.yaml') runs every
+  # host-buildable matrix entry and returns Builder::Result.
+  def self.build(manifest, entry_id: nil, root: Dir.pwd, output_base: nil, version: nil,
+                 host_os: Platform.os, host_arch: Platform.arch)
+    m = manifest.is_a?(BuildManifest) ? manifest : BuildManifest.load(manifest)
+    Builder.new(m, root: root, output_base: output_base, version: version,
+                host_os: host_os, host_arch: host_arch).run(entry_id: entry_id)
+  end
+end

data/lib/crosspack/builders/app_dir.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Crosspack
+  module Builders
+    # Stages a macOS .app bundle directory (MyApp.app/Contents/...). A real
+    # DMG requires hdiutil (macOS only); from Linux this directory layout is
+    # the honest maximum — it can be zipped or wrapped into a DMG on a Mac
+    # as-is.
+    class AppDir
+      # files: { source_path => basename inside Contents/MacOS }
+      # executables: basenames to chmod 0755
+      def self.build(name:, version:, summary:, files:, executables: [],
+                     identifier: nil, output:)
+        app_dir = File.join(output, "#{name}.app")
+        FileUtils.rm_rf(app_dir)
+        macos_dir = File.join(app_dir, 'Contents', 'MacOS')
+        resources_dir = File.join(app_dir, 'Contents', 'Resources')
+        FileUtils.mkdir_p(macos_dir)
+        FileUtils.mkdir_p(resources_dir)
+
+        missing = files.reject { |src, _dst| File.file?(src) }
+        unless missing.empty?
+          details = missing.map { |src, dst| "  ✗ #{src} (for #{dst})" }.join("\n")
+          raise BuildError,
+                "Source files for packing not found:\n#{details}\n" \
+                'Build the application for the target platform first.'
+        end
+
+        files.each do |src, dst|
+          target = File.join(macos_dir, dst)
+          FileUtils.cp(src, target)
+          FileUtils.chmod(executables.include?(dst) ? 0o755 : 0o644, target)
+        end
+
+        write_info_plist(File.join(app_dir, 'Contents', 'Info.plist'),
+                         name: name, version: version, summary: summary,
+                         identifier: identifier)
+
+        File.write(File.join(output, 'BUILD-DMG.txt'), <<~TXT)
+          DMG not built: hdiutil only exists on macOS.
+          On a Mac:  hdiutil create -volname #{name} -srcfolder #{name}.app -ov -format UDZO #{name}-#{version}.dmg
+          Or archive the bundle:  zip -r #{name}-#{version}.zip #{name}.app
+        TXT
+        app_dir
+      end
+
+      def self.write_info_plist(path, name:, version:, summary:, identifier: nil)
+        bundle_id = identifier || "org.crosspack.#{name}"
+        File.write(path, <<~PLIST)
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>CFBundleName</key>
+            <string>#{name}</string>
+            <key>CFBundleDisplayName</key>
+            <string>#{name}</string>
+            <key>CFBundleExecutable</key>
+            <string>#{name}</string>
+            <key>CFBundleIdentifier</key>
+            <string>#{bundle_id}</string>
+            <key>CFBundlePackageType</key>
+            <string>APPL</string>
+            <key>CFBundleShortVersionString</key>
+            <string>#{version}</string>
+            <key>CFBundleVersion</key>
+            <string>#{version}</string>
+            <key>CFBundleInfoDictionaryVersion</key>
+            <string>6.0</string>
+            <key>LSMinimumSystemVersion</key>
+            <string>11.0</string>
+            <key>NSPrincipalClass</key>
+            <string>NSApplication</string>
+            <key>NSSupportsAutomaticTermination</key>
+            <true/>
+            <key>NSSupportsSuddenTermination</key>
+            <false/>
+            <key>NSMicrophoneUsageDescription</key>
+            <string>#{summary}</string>
+          </dict>
+          </plist>
+        PLIST
+      end
+    end
+  end
+end

data/lib/crosspack/builders/deb.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+
+module Crosspack
+  module Builders
+    # Stages a package tree and packs it with dpkg-deb. No external Ruby
+    # dependencies; mirrors the layout conventions used by the hvoice
+    # Rakefile (files under a prefix, launcher symlink in bin).
+    class Deb
+      def self.build(name:, version:, architecture:, maintainer:, description:,
+                     depends:, files:, symlinks: {}, executables: [],
+                     section: 'utils', priority: 'optional', output:)
+        new(name: name, version: version, architecture: architecture,
+            maintainer: maintainer, description: description, depends: depends,
+            files: files, symlinks: symlinks, executables: executables,
+            section: section, priority: priority, output: output).build
+      end
+
+      def initialize(name:, version:, architecture:, maintainer:, description:,
+                     depends:, files:, symlinks:, executables:, section:,
+                     priority:, output:)
+        @name = name
+        @version = version
+        @architecture = architecture
+        @maintainer = maintainer
+        @description = description.to_s
+        @depends = depends
+        @files = files || {}
+        @symlinks = symlinks || {}
+        @executables = executables || []
+        @section = section
+        @priority = priority
+        @output = output
+      end
+
+      def build
+        check_tool!
+        stage_dir = File.join(File.dirname(@output), ".stage-#{@name}")
+        pkg_root = File.join(stage_dir, @name)
+        FileUtils.rm_rf(stage_dir)
+        FileUtils.mkdir_p(pkg_root)
+
+        stage_files(pkg_root)
+        stage_symlinks(pkg_root)
+        write_control(File.join(pkg_root, 'DEBIAN'))
+
+        FileUtils.mkdir_p(File.dirname(@output))
+        FileUtils.rm_f(@output)
+        out, status = Open3.capture2e('dpkg-deb', '--build', '--root-owner-group', pkg_root, @output)
+        unless status.success?
+          raise BuildError,
+                "dpkg-deb failed to build the package #{@output}:\n#{out}\n" \
+                'Check the package structure in the staging directory above.'
+        end
+        FileUtils.rm_rf(stage_dir)
+        @output
+      end
+
+      private
+
+      def check_tool!
+        _, _, status = Open3.capture3('dpkg-deb', '--version')
+        return if status.success?
+
+        raise BuildError, 'dpkg-deb not found in PATH. Install it with: sudo apt install dpkg'
+      rescue Errno::ENOENT
+        raise BuildError, 'dpkg-deb not found in PATH. Install it with: sudo apt install dpkg'
+      end
+
+      def stage_files(pkg_root)
+        missing = @files.reject { |src, _dst| File.file?(src) }
+        unless missing.empty?
+          details = missing.map { |src, dst| "  ✗ #{src} (for #{dst})" }.join("\n")
+          raise BuildError,
+                "Source files for packing not found:\n#{details}\n" \
+                'Build the application first (e.g. rake build:ubuntu).'
+        end
+
+        @files.each do |src, dst|
+          target = File.join(pkg_root, dst)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp(src, target)
+          FileUtils.chmod(executable?(dst) ? 0o755 : 0o644, target)
+        end
+      end
+
+      def stage_symlinks(pkg_root)
+        @symlinks.each do |link, target|
+          link_path = File.join(pkg_root, link)
+          FileUtils.mkdir_p(File.dirname(link_path))
+          FileUtils.ln_sf(target, link_path)
+        end
+      end
+
+      def executable?(dst)
+        @executables.include?(dst)
+      end
+
+      def write_control(debian_dir)
+        FileUtils.mkdir_p(debian_dir)
+        description_lines = @description.lines.map(&:chomp).reject(&:empty?)
+        summary = description_lines.shift || @name
+        body = description_lines.map { |l| " #{l}" }
+
+        File.write(File.join(debian_dir, 'control'), <<~CONTROL)
+          Package: #{@name}
+          Version: #{@version}
+          Section: #{@section}
+          Priority: #{@priority}
+          Architecture: #{@architecture}
+          Maintainer: #{@maintainer}
+          Depends: #{@depends}
+          Description: #{summary}
+          #{body.join("\n")}
+        CONTROL
+      end
+    end
+  end
+end

data/lib/crosspack/builders/pkgbuild.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Crosspack
+  module Builders
+    # Generates a PKGBUILD for AUR from the same file layout as the deb/rpm
+    # builders. `files` keys are paths *inside the extracted source archive*
+    # (relative to "$srcdir/$pkgname-$pkgver"), values are destinations in
+    # the package root.
+    class Pkgbuild
+      def self.generate(name:, version:, release:, pkgdesc:, depends:, arch:,
+                        files:, symlinks: {}, executables: [], source:,
+                        maintainer:, url: '', license: 'Proprietary', output:)
+        content = render(
+          name: name, version: version, release: release, pkgdesc: pkgdesc,
+          depends: Array(depends), arch: Array(arch), files: files,
+          symlinks: symlinks, executables: executables, source: Array(source),
+          maintainer: maintainer, url: url, license: license
+        )
+        FileUtils.mkdir_p(File.dirname(output))
+        File.write(output, content)
+        output
+      end
+
+      def self.render(name:, version:, release:, pkgdesc:, depends:, arch:,
+                      files:, symlinks:, executables:, source:, maintainer:,
+                      url:, license:)
+        depends_line = depends.map { |d| "'#{d}'" }.join(' ')
+        source_line = source.map { |s| "'#{s}'" }.join(' ')
+        srcbase = "$srcdir/$pkgname-$pkgver"
+        escaped_desc = pkgdesc.gsub("'", %q{'\''})
+
+        install_lines = files.map do |src, dst|
+          mode = executables.include?(dst) ? '755' : '644'
+          "  install -Dm#{mode} \"#{File.join(srcbase, src)}\" \"$pkgdir/#{dst}\""
+        end
+        link_lines = symlinks.map do |link, target|
+          "  install -d \"$(dirname \"$pkgdir/#{File.dirname(link)}\")\"\n" \
+            "  ln -s #{target} \"$pkgdir/#{link}\""
+        end
+
+        <<~PKGBUILD
+          # Maintainer: #{maintainer}
+          # Generated by crosspack — edit deps.yaml, not this file.
+          pkgname=#{name}
+          pkgver=#{version}
+          pkgrel=#{release}
+          pkgdesc='#{escaped_desc}'
+          arch=(#{arch.join(' ')})
+          url='#{url}'
+          license=(#{license})
+          depends=(#{depends_line})
+          source=(#{source_line})
+          sha256sums=('SKIP')
+
+          package() {
+          #{(install_lines + link_lines).join("\n")}
+          }
+        PKGBUILD
+      end
+    end
+  end
+end

data/lib/crosspack/builders/rpm.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+require 'tmpdir'
+
+module Crosspack
+  module Builders
+    # Stages a buildroot and packs it with rpmbuild. The spec is generated
+    # with AutoReqProv disabled so dependency names come exclusively from
+    # deps.yaml (resolved per target), never from ELF soname scanning.
+    class Rpm
+      def self.build(name:, version:, release:, summary:, license:, requires:,
+                     files:, symlinks: {}, executables: [], description: nil,
+                     arch: 'x86_64', output:)
+        spec = generate_spec(name: name, version: version, release: release,
+                             summary: summary, license: license, requires: requires,
+                             description: description, files: files,
+                             symlinks: symlinks)
+        new(spec: spec, files: files, symlinks: symlinks,
+            executables: executables, arch: arch, output: output).build
+      end
+
+      # The spec text, separated from #build so tests can check it without
+      # having rpmbuild installed.
+      def self.generate_spec(name:, version:, release:, summary:, license:,
+                             requires:, description: nil, files:, symlinks: {})
+        description ||= summary
+        requires_line = Array(requires).join(', ')
+        entries = spec_entries(files: files, symlinks: symlinks)
+
+        <<~SPEC
+          Name: #{name}
+          Version: #{version}
+          Release: #{release}
+          Summary: #{summary}
+          License: #{license}
+          AutoReqProv: no
+          #{requires_line.empty? ? '' : "Requires: #{requires_line}"}
+          %description
+          #{description}
+
+          %prep
+
+          %build
+
+          %install
+          # Files are staged into the buildroot by crosspack.
+
+          %files
+          %defattr(-,root,root,-)
+          #{entries.join("\n")}
+        SPEC
+      end
+
+      # %files entries: %dir for every directory so we never claim ownership
+      # of shared paths like /usr or /usr/local.
+      def self.spec_entries(files:, symlinks:)
+        dirs = Set.new
+        (files.values + symlinks.keys).each do |dst|
+          parts = dst.split(File::SEPARATOR)
+          parts.pop
+          until parts.empty?
+            dirs << parts.join(File::SEPARATOR)
+            parts.pop
+          end
+        end
+        # Never claim ownership of directories every system already has.
+        skip = ->(d) { d.split(File::SEPARATOR).size == 1 || d == 'usr/local' }
+        sorted_dirs = dirs.to_a.sort.reject { |d| skip.call(d) }.map { |d| "%dir /#{d}" }
+        file_lines = files.values.map { |dst| "/#{dst}" }
+        link_lines = symlinks.keys.map { |dst| "/#{dst}" }
+        sorted_dirs + file_lines + link_lines
+      end
+
+      def initialize(spec:, files:, symlinks:, executables:, arch:, output:)
+        @spec = spec
+        @files = files
+        @symlinks = symlinks
+        @executables = executables
+        @arch = arch
+        @output = output
+      end
+
+      def build
+        check_tool!
+        missing = @files.reject { |src, _dst| File.file?(src) }
+        unless missing.empty?
+          details = missing.map { |src, dst| "  ✗ #{src} (for #{dst})" }.join("\n")
+          raise BuildError,
+                "Source files for packing not found:\n#{details}\n" \
+                'Build the application first (e.g. rake build:ubuntu).'
+        end
+
+        Dir.mktmpdir('crosspack-rpm') do |topdir|
+          buildroot = File.join(topdir, 'buildroot')
+          stage(buildroot)
+
+          spec_path = File.join(topdir, "#{File.basename(@output, '.rpm')}.spec")
+          File.write(spec_path, @spec)
+
+          %w[BUILD RPMS SOURCES SPECS SRPMS].each { |d| FileUtils.mkdir_p(File.join(topdir, d)) }
+
+          out, status = Open3.capture2e(
+            'rpmbuild', '-bb', "--target #{@arch}", "--define _topdir #{topdir}",
+            "--buildroot #{buildroot}", spec_path
+          )
+          unless status.success?
+            raise BuildError,
+                  "rpmbuild failed to build #{@output}:\n#{out}\n" \
+                  'Check the spec and the staging directory above.'
+          end
+
+          produced = Dir.glob(File.join(topdir, 'RPMS', '**', '*.rpm')).first
+          raise BuildError, "rpmbuild completed but no .rpm found in #{topdir}/RPMS:\n#{out}" unless produced
+
+          FileUtils.mkdir_p(File.dirname(@output))
+          FileUtils.cp(produced, @output)
+        end
+        @output
+      end
+
+      private
+
+      def check_tool!
+        _, _, status = Open3.capture3('rpmbuild', '--version')
+        return if status.success?
+
+        raise BuildError, 'rpmbuild not found in PATH. Install it with: sudo apt install rpm'
+      rescue Errno::ENOENT
+        raise BuildError, 'rpmbuild not found in PATH. Install it with: sudo apt install rpm'
+      end
+
+      def stage(buildroot)
+        @files.each do |src, dst|
+          target = File.join(buildroot, dst)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp(src, target)
+          FileUtils.chmod(@executables.include?(dst) ? 0o755 : 0o644, target)
+        end
+        @symlinks.each do |link, target|
+          link_path = File.join(buildroot, link)
+          FileUtils.mkdir_p(File.dirname(link_path))
+          FileUtils.ln_sf(target, link_path)
+        end
+      end
+    end
+  end
+end

data/lib/crosspack/builders/wix.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+require 'digest'
+
+module Crosspack
+  module Builders
+    # Windows MSI packaging via the WiX toolset (wixtoolset.org). WiX v4+
+    # runs on Linux as a .NET tool, so real MSI builds are possible once
+    # `dotnet tool install -g wix` is available. Without it we still emit a
+    # complete .wxs source plus build instructions — packaging is not blocked
+    # by the toolchain.
+    class Wix
+      # MSI ProductVersion only honours three numeric fields (x.y.z).
+      def self.msi_version(version)
+        fields = version.to_s.split(/[.-]/).first(3)
+        fields << '0' while fields.size < 3
+        fields.map { |f| f.gsub(/\D/, '').empty? ? '0' : f.gsub(/\D/, '') }.join('.')
+      end
+
+      # Deterministic UpgradeCode derived from the package name, so upgrades
+      # chain across releases without a hand-maintained GUID.
+      def self.upgrade_code(name)
+        digest = Digest::SHA1.hexdigest("crosspack:#{name}")
+        hex = digest[0, 32].upcase
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+
+      def self.generate_wxs(name:, version:, manufacturer:, summary:, files:,
+                            arch: 'x64')
+        directory = arch == 'arm64' ? 'ProgramFiles6432Folder' : 'ProgramFiles64Folder'
+        components = files.values.each_with_index.map do |dst, i|
+          src = files.key(dst).gsub('/', '\\')
+          "      <Component Id=\"c#{i}\" Guid=\"*\">\n" \
+            "        <File Id=\"f#{i}\" Source=\"#{src}\" />\n" \
+            '      </Component>'
+        end.join("\n")
+
+        <<~WXS
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!-- Generated by crosspack. Build with: wix build -arch #{arch} -o #{name}.msi #{name}.wxs -->
+          <Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
+            <Package Name="#{name}" Manufacturer="#{manufacturer}" Version="#{msi_version(version)}"
+                     UpgradeCode="{#{upgrade_code(name)}}" Scope="perMachine">
+              <SummaryInformation Description="#{summary}" />
+              <MajorUpgrade DowngradeErrorMessage="A newer version of #{name} is already installed." />
+
+              <StandardDirectory Id="#{directory}">
+                <Directory Id="INSTALLDIR" Name="#{name}" />
+              </StandardDirectory>
+
+              <Feature Id="Main" Title="#{name}" Level="1">
+                <ComponentGroupRef Id="Payload" />
+              </Feature>
+            </Package>
+
+            <Fragment>
+              <ComponentGroup Id="Payload">
+          #{components}
+              </ComponentGroup>
+            </Fragment>
+          </Wix>
+        WXS
+      end
+
+      # Writes the .wxs next to the output and, when WiX is installed,
+      # builds a real MSI. Returns the path of whatever was produced.
+      def self.build(name:, version:, manufacturer:, summary:, files:, output:,
+                     arch: 'x64')
+        arch = { 'x86_64' => 'x64', 'aarch64' => 'arm64' }.fetch(arch, arch)
+        missing = files.reject { |src, _dst| File.file?(src) }
+        unless missing.empty?
+          details = missing.map { |src, dst| "  ✗ #{src} (for #{dst})" }.join("\n")
+          raise BuildError,
+                "Source files for packing not found:\n#{details}\n" \
+                'Build the application for the target platform first.'
+        end
+
+        out_dir = File.dirname(output)
+        FileUtils.mkdir_p(out_dir)
+        wxs_path = File.join(out_dir, "#{name}.wxs")
+        File.write(wxs_path, generate_wxs(name: name, version: version,
+                                          manufacturer: manufacturer,
+                                          summary: summary, files: files,
+                                          arch: arch))
+
+        wix = wix_command
+        unless wix
+          File.write(File.join(out_dir, 'BUILD-MSI.txt'), <<~TXT)
+            MSI not built: WiX toolset not found in PATH.
+            Install the .NET SDK and WiX:
+              dotnet tool install -g wix
+            Then build with:
+              wix build -arch #{arch} -o #{File.basename(output)} #{name}.wxs
+          TXT
+          return wxs_path
+        end
+
+        out, status = Open3.capture2e(wix, 'build', "-arch #{arch}",
+                                      '-o', output, wxs_path)
+        unless status.success?
+          raise BuildError, "wix build failed to build #{output}:\n#{out}"
+        end
+        output
+      end
+
+      def self.wix_command
+        %w[wix dotnet].each do |cmd|
+          _, _, status = Open3.capture3(cmd, '--version')
+          return cmd if status.success?
+        end
+        nil
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/crosspack/builds.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Crosspack
+  # Scans a builds tree laid out exactly like the output tree —
+  # builds/<family>[/<version>]/<arch>/ — and reports which targets have
+  # compiled artifacts ready for packing. A missing directory simply means
+  # "nothing to pack for that target".
+  module Builds
+    ARCH_DIR_RE = /\A(amd64|x86_64|x64|arm64|aarch64)\z/i.freeze
+
+    # Returns [Target] for every target directory found under root.
+    def self.available(root)
+      return [] unless File.directory?(root)
+
+      Dir.glob(File.join(root, '*')).sort.flat_map do |family_dir|
+        family = File.basename(family_dir).to_sym
+        next [] unless Target::FAMILIES.include?(family)
+
+        scan_family(family_dir, family)
+      end
+    end
+
+    # Human-readable listing: "ubuntu/25.10/amd64 — builds/ubuntu/25.10/amd64".
+    def self.report(root)
+      targets = available(root)
+      return "No compiled artifacts: the #{root} tree is empty or missing." if targets.empty?
+
+      lines = ["Available builds in #{root}:"]
+      targets.each { |t| lines << "  #{t}  (#{t.output_dir(root, t.format)})" }
+      lines.join("\n")
+    end
+
+    private
+
+    def self.scan_family(dir, family)
+      results = []
+      Dir.glob(File.join(dir, '*')).select { |e| File.directory?(e) }.each do |entry|
+        base = File.basename(entry)
+        if versionless_segment?(family, base)
+          # The entry is an arch directory directly under the family
+          # (e.g. builds/arch/x86_64, builds/macos/arm64).
+          add_target(results, family, nil, base)
+        else
+          Dir.glob(File.join(entry, '*')).select { |d| File.directory?(d) }.each do |arch_dir|
+            add_target(results, family, base, File.basename(arch_dir))
+          end
+        end
+      end
+      results
+    end
+
+    def self.versionless_segment?(family, base)
+      Target::VERSIONLESS_FAMILIES.include?(family) || base.match?(ARCH_DIR_RE)
+    end
+
+    def self.add_target(results, family, version, arch_name)
+      arch = Target.normalize_arch(arch_name)
+      results << Target.new(family, version, arch) unless arch.nil?
+    end
+  end
+end