zui 0.0.6 → 0.0.8

data/lib/zui/cli.rb

@@ -5,7 +5,7 @@ require "rbconfig"
 
 module Zui
   class CLI
-    USAGE = "Usage: zui <new NAME|configure|doctor [--fix]|run FILE|bundle [DIRECTORY]|version>"
+    USAGE = "Usage: zui <new NAME|configure|doctor [--fix]|run FILE|bundle [--dist] [--lite|--full] [--no-tree-shake] [DIRECTORY]|version>"
 
     def self.run(arguments, out: $stdout, err: $stderr)
       new(out:, err:).run(arguments.dup)
@@ -56,13 +56,38 @@ module Zui
     def bundle_project(arguments)
       name = option_value(arguments, "--name")
       destination = option_value(arguments, "--output")
+      create_installers = !arguments.delete("--dist").nil?
+      tree_shake = arguments.delete("--no-tree-shake").nil?
+      lite = !arguments.delete("--lite").nil?
+      full = !arguments.delete("--full").nil?
+      raise ArgumentError, "bundle accepts only one of --lite or --full" if lite && full
+      runtime_mode = full ? :full : :lite
       source = File.expand_path(arguments.shift || Dir.pwd)
       raise ArgumentError, "bundle accepts one directory" unless arguments.empty?
-      path = Distribution.new.bundle(source, name:, destination:)
+
+      if create_installers
+        raise ArgumentError, "--name cannot be used with --dist; set name in config.rb" if name
+
+        packager = DistPackager.new(tree_shake:, runtime_mode:)
+        paths = packager.package(source, output: destination)
+        paths.each { |path| @out.puts("Created distribution artifact #{path}") }
+        report_tree_shaking(packager.tree_shake_report)
+        return 0
+      end
+
+      distribution = Distribution.new(tree_shake:, runtime_mode:)
+      path = distribution.bundle(source, name:, destination:)
       @out.puts("Bundled #{Platform.current.os} application in #{path}")
+      report_tree_shaking(distribution.tree_shake_report)
       0
     end
 
+    def report_tree_shaking(report)
+      return unless report
+
+      @out.puts("Tree-shaken runtime: #{report.components.length} components, #{format_bytes(report.saved_bytes)} removed")
+    end
+
     def doctor(arguments)
       fix = arguments.delete("--fix")
       raise ArgumentError, "doctor accepts only --fix" unless arguments.empty?
@@ -73,17 +98,27 @@ module Zui
       return 1 unless platform.supported?
 
       client = Client.new(platform:)
-      if client.configured?
-        report_ready(client)
+      lite_runtime = LiteRuntime.new(platform:)
+      client_ready = client.configured?
+      lite_ready = lite_runtime.configured?
+      if client_ready && lite_ready
+        report_ready(client, lite_runtime)
         0
       elsif fix
-        @out.puts("Repair: downloading the verified native client from GitHub Releases...")
-        client.configure!
-        report_ready(client)
+        unless client_ready
+          @out.puts("Repair: downloading the verified native client from GitHub Releases...")
+          client.configure!
+        end
+        unless lite_ready
+          @out.puts("Repair: downloading the verified lite mruby runtime from GitHub Releases...")
+          lite_runtime.configure!
+        end
+        report_ready(client, lite_runtime)
         0
       else
-        @out.puts("Client: not configured")
-        @out.puts("Run `zui doctor --fix` to install the native client and bundle support.")
+        @out.puts(client_ready ? "Client: #{client.root}" : "Client: not configured")
+        @out.puts(lite_ready ? "Lite runtime: #{lite_runtime.root}" : "Lite runtime: not configured")
+        @out.puts("Run `zui doctor --fix` to install the native client and lite bundle runtime.")
         1
       end
     end
@@ -92,16 +127,20 @@ module Zui
       raise ArgumentError, "configure accepts no arguments" unless arguments.empty?
       platform = Platform.current.assert_supported!
       client = Client.new(platform:)
+      lite_runtime = LiteRuntime.new(platform:)
       @out.puts("Configuring Zui #{VERSION} for #{platform.id}...")
       client.configure!
-      report_ready(client)
+      lite_runtime.configure!
+      report_ready(client, lite_runtime)
       0
     end
 
-    def report_ready(client)
+    def report_ready(client, lite_runtime)
       @out.puts("Client: #{client.root}")
+      @out.puts("Lite runtime: #{lite_runtime.root}")
       @out.puts("Run: ready")
-      @out.puts("Bundle: ready")
+      @out.puts("Bundle --lite: ready")
+      @out.puts("Bundle --full: ready (uses this Ruby and the project's locked gems)")
     end
 
     def option_value(arguments, name)
@@ -117,5 +156,16 @@ module Zui
       raise ArgumentError, "name must contain letters or numbers" if result.empty?
       result
     end
+
+    def format_bytes(bytes)
+      units = %w[B KB MB GB]
+      value = bytes.to_f
+      unit = units.shift
+      while value >= 1024 && !units.empty?
+        value /= 1024
+        unit = units.shift
+      end
+      value >= 10 || unit == "B" ? "#{value.round} #{unit}" : format("%.1f %s", value, unit)
+    end
   end
 end

data/lib/zui/component_registry.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
 module Zui
-  Component = Struct.new(:name, :qml, :properties, :events, :property_map, :event_map, :container, :auto_bind, keyword_init: true) do
+  class Component
+    attr_reader :name, :qml, :properties, :events, :property_map, :event_map, :container, :auto_bind
+
+    def initialize(name:, qml:, properties:, events:, property_map:, event_map:, container:, auto_bind:)
+      @name = name
+      @qml = qml
+      @properties = properties
+      @events = events
+      @property_map = property_map
+      @event_map = event_map
+      @container = container
+      @auto_bind = auto_bind
+    end
+
     def to_h
       {
         "qml" => qml,

data/lib/zui/dist_config.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Zui
+  module Dist
+    CONFIG_FILE = "config.rb"
+    UNSET = Object.new.freeze
+    PLATFORM_ICON_EXTENSIONS = {
+      linux: %w[.png .svg],
+      macos: %w[.icns],
+      windows: %w[.ico]
+    }.freeze
+
+    class Config
+      attr_reader :name, :identifier, :version, :publisher, :description, :license,
+                  :homepage, :icons, :categories
+
+      def initialize(name:, identifier:, version:, publisher:, description:, license:,
+                     homepage:, icons:, categories:)
+        @name = name
+        @identifier = identifier
+        @version = version
+        @publisher = publisher
+        @description = description
+        @license = license
+        @homepage = homepage
+        @icons = icons.transform_keys(&:to_sym).transform_values(&:to_s).freeze
+        @categories = categories.map(&:to_s).freeze
+        freeze
+      end
+
+      def validate!(project:, platform:)
+        project = File.realpath(project)
+        validate_text!("name", name, maximum: 100)
+        validate_text!("publisher", publisher, maximum: 200)
+        validate_text!("description", description, maximum: 500)
+        validate_text!("license", license, maximum: 100)
+        if homepage
+          validate_text!("homepage", homepage, maximum: 500)
+          unless homepage.match?(%r{\Ahttps?://[^\s]+\z})
+            raise ArgumentError, "#{CONFIG_FILE} homepage must be an HTTP or HTTPS URL"
+          end
+        end
+        unless identifier.to_s.match?(/\A[a-z][a-z0-9]*(?:\.[a-z][a-z0-9-]*)+\z/)
+          raise ArgumentError, "#{CONFIG_FILE} identifier must be a lowercase reverse-DNS name"
+        end
+        unless version.to_s.match?(/\A\d+\.\d+\.\d+\z/)
+          raise ArgumentError, "#{CONFIG_FILE} version must have three numeric parts, such as 1.2.0"
+        end
+        if categories.empty? || categories.any? { |value| !value.match?(/\A[A-Za-z][A-Za-z0-9-]*\z/) }
+          raise ArgumentError, "#{CONFIG_FILE} categories must contain portable desktop category names"
+        end
+
+        icon_path(project, platform)
+        self
+      end
+
+      def package_name
+        value = name.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+        raise ArgumentError, "#{CONFIG_FILE} name must contain letters or numbers" if value.empty?
+
+        value.length < 2 ? "zui-#{value}" : value
+      end
+
+      def icon_path(project, platform)
+        os = platform.os
+        relative = icons[os]
+        raise ArgumentError, "#{CONFIG_FILE} must declare icon #{os}: \"path\"" if relative.nil? || relative.empty?
+        if Pathname.new(relative).absolute? || relative.include?("\0")
+          raise ArgumentError, "#{CONFIG_FILE} #{os} icon must be a project-relative path"
+        end
+
+        path = File.expand_path(relative, project)
+        unless File.file?(path)
+          raise ArgumentError, "#{CONFIG_FILE} #{os} icon was not found: #{relative}"
+        end
+        real_path = File.realpath(path)
+        unless real_path.start_with?("#{File.realpath(project)}#{File::SEPARATOR}")
+          raise ArgumentError, "#{CONFIG_FILE} #{os} icon must stay inside the project"
+        end
+        extension = File.extname(real_path).downcase
+        allowed = PLATFORM_ICON_EXTENSIONS.fetch(os)
+        unless allowed.include?(extension)
+          raise ArgumentError, "#{CONFIG_FILE} #{os} icon must use #{allowed.join(' or ')}"
+        end
+        raise ArgumentError, "#{CONFIG_FILE} icon is too large" if File.size(real_path) > 20 * 1024 * 1024
+
+        validate_icon_signature!(real_path, extension)
+        real_path
+      end
+
+      private
+
+      def validate_text!(field, value, maximum:)
+        unless value.is_a?(String) && !value.strip.empty? && value.bytesize <= maximum &&
+               !value.match?(/[\r\n\0]/)
+          raise ArgumentError, "#{CONFIG_FILE} #{field} must be a single non-empty line"
+        end
+      end
+
+      def validate_icon_signature!(path, extension)
+        header = File.binread(path, 512)
+        valid = case extension
+                when ".png" then header.start_with?("\x89PNG\r\n\x1a\n".b)
+                when ".svg" then header.match?(/<svg\b/i)
+                when ".icns" then header.start_with?("icns")
+                when ".ico" then header.start_with?("\x00\x00\x01\x00".b)
+                end
+        raise ArgumentError, "#{CONFIG_FILE} icon contents do not match #{extension}" unless valid
+      end
+    end
+
+    class Builder
+      def initialize
+        @values = { homepage: nil, icons: {}, categories: ["Utility"] }
+      end
+
+      %i[name identifier version publisher description license homepage].each do |field|
+        define_method(field) do |value = UNSET|
+          raise ArgumentError, "#{field} requires a value" if value.equal?(UNSET)
+
+          @values[field] = value.to_s
+        end
+      end
+
+      def icon(**paths)
+        unknown = paths.keys.map(&:to_sym) - PLATFORM_ICON_EXTENSIONS.keys
+        raise ArgumentError, "unknown icon platform: #{unknown.first}" unless unknown.empty?
+
+        @values[:icons].merge!(paths.transform_keys(&:to_sym))
+      end
+
+      def categories(*values)
+        @values[:categories] = values.flatten.map(&:to_s)
+      end
+
+      def build
+        required = %i[name identifier version publisher description license]
+        missing = required.reject { |field| @values.key?(field) }
+        unless missing.empty?
+          raise ArgumentError, "#{CONFIG_FILE} is missing: #{missing.join(', ')}"
+        end
+
+        Config.new(**@values)
+      end
+    end
+
+    module_function
+
+    def configure(&block)
+      raise ArgumentError, "Dist.configure requires a block" unless block
+
+      builder = Builder.new
+      block.arity == 1 ? block.call(builder) : builder.instance_eval(&block)
+      builder.build
+    end
+
+    def load(project:, platform: Platform.current)
+      project = File.expand_path(project)
+      path = File.join(project, CONFIG_FILE)
+      raise ArgumentError, "#{CONFIG_FILE} not found in project root" unless File.file?(path)
+      raise ArgumentError, "#{CONFIG_FILE} is too large" if File.size(path) > 131_072
+
+      value = Module.new.module_eval(File.read(path), path, 1)
+      unless value.is_a?(Config)
+        raise ArgumentError, "#{CONFIG_FILE} must return Zui::Dist.configure do ... end"
+      end
+      value.validate!(project:, platform: platform.assert_supported!)
+    rescue SyntaxError => error
+      raise ArgumentError, "invalid #{CONFIG_FILE}: #{error.message.lines.first.to_s.strip}"
+    rescue ScriptError => error
+      raise ArgumentError, "#{CONFIG_FILE} failed: #{error.class}: #{error.message}"
+    rescue ArgumentError
+      raise
+    rescue StandardError => error
+      raise ArgumentError, "#{CONFIG_FILE} failed: #{error.class}: #{error.message}"
+    end
+  end
+end

data/lib/zui/dist_packager.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+require "rubygems/package"
+require "shellwords"
+require "tmpdir"
+require "zlib"
+
+module Zui
+  class DistPackager
+    attr_reader :platform, :config, :tree_shake_report, :runtime_mode
+
+    def initialize(client: nil, platform: Platform.current, framework_root: FRAMEWORK_ROOT,
+                   ruby: RbConfig.ruby, tree_shake: true, environment: ENV, runtime_mode: :lite,
+                   runtime_builder: nil)
+      @platform = platform.assert_supported!
+      @client = client || Client.new(platform: @platform)
+      @framework_root = framework_root
+      @ruby = File.expand_path(ruby)
+      @tree_shake = tree_shake == true
+      @runtime_mode = runtime_mode.to_sym
+      unless Distribution::RUNTIME_MODES.include?(@runtime_mode)
+        raise ArgumentError, "unsupported application runtime: #{runtime_mode}"
+      end
+      @environment = environment.to_h
+      @runtime_builder = runtime_builder
+      @config = nil
+      @tree_shake_report = nil
+    end
+
+    def package(source, output: nil)
+      project = File.expand_path(source)
+      raise ArgumentError, "project directory not found: #{project}" unless File.directory?(project)
+
+      @project = project
+      @config = Dist.load(project:, platform:)
+      output = File.expand_path(output || File.join(project, "dist"))
+      if File.exist?(output) && !File.directory?(output)
+        raise ArgumentError, "distribution output is not a directory: #{output}"
+      end
+      preflight!
+      targets = artifact_names.map { |name| File.join(output, name) }
+      existing = targets.find { |path| File.exist?(path) }
+      raise ArgumentError, "distribution artifact already exists: #{existing}" if existing
+
+      FileUtils.mkdir_p(output)
+      artifacts = []
+      Dir.mktmpdir(".zui-dist-", output) do |temporary|
+        bundle = build_bundle(project, temporary)
+        artifacts = case platform.os
+                    when :linux then build_linux_packages(bundle, temporary)
+                    when :macos then [build_macos_dmg(bundle, temporary)]
+                    when :windows then [build_windows_setup(bundle, temporary)]
+                    end
+        artifacts.zip(targets).each { |source_path, target| File.rename(source_path, target) }
+      end
+      targets
+    end
+
+    private
+
+    def build_bundle(project, temporary)
+      destination = if platform.macos?
+                      File.join(temporary, "#{safe_filename(config.name)}.app")
+                    else
+                      File.join(temporary, "bundle")
+                    end
+      distribution = Distribution.new(
+        client: @client, platform:, framework_root: @framework_root, ruby: @ruby,
+        tree_shake: @tree_shake, release_config: config, runtime_mode:,
+        runtime_builder: @runtime_builder
+      )
+      distribution.bundle(project, name: config.name, destination:)
+      @tree_shake_report = distribution.tree_shake_report
+      destination
+    end
+
+    def artifact_names
+      stem = "#{config.package_name}-#{config.version}-#{platform.id}"
+      case platform.os
+      when :linux
+        ["#{stem}.deb", "#{stem}.rpm"]
+      when :macos
+        ["#{stem}.dmg"]
+      when :windows
+        ["#{stem}-setup.exe"]
+      end
+    end
+
+    def preflight!
+      case platform.os
+      when :linux
+        command!("rpmbuild", hint: "install rpm-build (Debian/Fedora) or rpm-tools (Arch)")
+      when :macos
+        command!("hdiutil", hint: "install the macOS command-line tools")
+      when :windows
+        command!("ISCC.exe", "iscc", hint: "install Inno Setup 6 and add ISCC.exe to PATH")
+      end
+    end
+
+    def build_linux_packages(bundle, temporary)
+      stage = File.join(temporary, "linux-root")
+      application = File.join(stage, "opt", config.package_name)
+      FileUtils.mkdir_p(File.dirname(application))
+      FileUtils.cp_r(bundle, application)
+      FileUtils.remove_entry(File.join(application, "share")) if File.directory?(File.join(application, "share"))
+
+      command_path = File.join(stage, "usr", "bin", config.package_name)
+      FileUtils.mkdir_p(File.dirname(command_path))
+      File.write(command_path, <<~SH)
+        #!/bin/sh
+        exec /opt/#{config.package_name}/run "$@"
+      SH
+      FileUtils.chmod(0o755, command_path)
+
+      desktop_path = File.join(stage, "usr", "share", "applications", "#{config.package_name}.desktop")
+      FileUtils.mkdir_p(File.dirname(desktop_path))
+      File.write(desktop_path, linux_desktop_entry)
+
+      icon = config.icon_path(@project, platform)
+      extension = File.extname(icon).downcase
+      icon_directory = extension == ".svg" ? "scalable" : "256x256"
+      installed_icon = File.join(stage, "usr", "share", "icons", "hicolor", icon_directory,
+                                 "apps", "#{config.package_name}#{extension}")
+      FileUtils.mkdir_p(File.dirname(installed_icon))
+      FileUtils.cp(icon, installed_icon)
+
+      deb = File.join(temporary, artifact_names.fetch(0))
+      rpm = File.join(temporary, artifact_names.fetch(1))
+      build_deb(stage, deb)
+      build_rpm(stage, rpm, temporary)
+      [deb, rpm]
+    end
+
+    def linux_desktop_entry
+      categories = config.categories.join(";")
+      <<~DESKTOP
+        [Desktop Entry]
+        Type=Application
+        Name=#{config.name}
+        Comment=#{config.description}
+        Exec=/opt/#{config.package_name}/run
+        Icon=#{config.package_name}
+        Terminal=false
+        Categories=#{categories};
+      DESKTOP
+    end
+
+    def build_deb(stage, output)
+      workspace = File.join(File.dirname(output), "deb-work")
+      FileUtils.mkdir_p(workspace)
+      control = File.join(workspace, "control")
+      File.write(control, deb_control(stage))
+      debian_binary = File.join(workspace, "debian-binary")
+      File.write(debian_binary, "2.0\n")
+      control_archive = File.join(workspace, "control.tar.gz")
+      data_archive = File.join(workspace, "data.tar.gz")
+      gzip_tar(control_archive, workspace, ["control"])
+      gzip_tar(data_archive, stage, Dir.children(stage).sort)
+      write_ar(output, [debian_binary, control_archive, data_archive])
+    end
+
+    def deb_control(stage)
+      installed_size = (tree_bytes(stage) / 1024.0).ceil
+      values = [
+        "Package: #{config.package_name}",
+        "Version: #{config.version}",
+        "Section: utils",
+        "Priority: optional",
+        "Architecture: #{deb_architecture}",
+        "Maintainer: #{config.publisher}",
+        "Installed-Size: #{installed_size}",
+        "Description: #{config.description}"
+      ]
+      values.insert(-2, "Homepage: #{config.homepage}") if config.homepage
+      "#{values.join("\n")}\n"
+    end
+
+    def build_rpm(stage, output, temporary)
+      topdir = File.join(temporary, "rpmbuild")
+      %w[BUILD BUILDROOT RPMS SOURCES SPECS SRPMS].each { |name| FileUtils.mkdir_p(File.join(topdir, name)) }
+      spec = File.join(topdir, "SPECS", "#{config.package_name}.spec")
+      File.write(spec, rpm_spec(stage))
+      rpmbuild = command!("rpmbuild", hint: "install rpm-build (Debian/Fedora) or rpm-tools (Arch)")
+      run!([rpmbuild, "--define", "_topdir #{topdir}", "-bb", spec], timeout: 900)
+      built = Dir[File.join(topdir, "RPMS", "**", "*.rpm")].sort
+      raise ArgumentError, "rpmbuild did not produce an RPM artifact" unless built.length == 1
+
+      FileUtils.cp(built.first, output)
+    end
+
+    def rpm_spec(stage)
+      description = rpm_escape(config.description)
+      homepage = config.homepage ? "URL: #{rpm_escape(config.homepage)}\n" : ""
+      <<~SPEC
+        %global debug_package %{nil}
+        Name: #{config.package_name}
+        Version: #{config.version}
+        Release: 1
+        Summary: #{description}
+        License: #{rpm_escape(config.license)}
+        #{homepage}BuildArch: #{rpm_architecture}
+        AutoReqProv: no
+
+        %description
+        #{description}
+
+        %install
+        rm -rf "%{buildroot}"
+        mkdir -p "%{buildroot}"
+        cp -a #{Shellwords.escape(stage)}/. "%{buildroot}/"
+
+        %files
+        /opt/#{config.package_name}
+        /usr/bin/#{config.package_name}
+        /usr/share/applications/#{config.package_name}.desktop
+        /usr/share/icons/hicolor
+      SPEC
+    end
+
+    def build_macos_dmg(bundle, temporary)
+      root = File.join(temporary, "dmg-root")
+      FileUtils.mkdir_p(root)
+      FileUtils.cp_r(bundle, root)
+      File.symlink("/Applications", File.join(root, "Applications"))
+      output = File.join(temporary, artifact_names.first)
+      hdiutil = command!("hdiutil", hint: "install the macOS command-line tools")
+      run!([hdiutil, "create", "-volname", config.name, "-srcfolder", root,
+            "-ov", "-format", "UDZO", output], timeout: 900)
+      raise ArgumentError, "hdiutil did not produce a DMG artifact" unless File.file?(output)
+
+      output
+    end
+
+    def build_windows_setup(bundle, temporary)
+      output_name = File.basename(artifact_names.first, ".exe")
+      script = File.join(temporary, "installer.iss")
+      File.write(script, windows_inno_script(bundle, temporary, output_name))
+      iscc = command!("ISCC.exe", "iscc", hint: "install Inno Setup 6 and add ISCC.exe to PATH")
+      run!([iscc, script], timeout: 900)
+      output = File.join(temporary, "#{output_name}.exe")
+      raise ArgumentError, "Inno Setup did not produce a setup executable" unless File.file?(output)
+
+      output
+    end
+
+    def windows_inno_script(bundle, output, output_name)
+      architectures = platform.arch == :arm64 ? "arm64" : "x64compatible"
+      <<~ISS
+        [Setup]
+        AppId=#{inno(config.identifier)}
+        AppName=#{inno(config.name)}
+        AppVersion=#{inno(config.version)}
+        AppPublisher=#{inno(config.publisher)}
+        AppPublisherURL=#{inno(config.homepage || "")}
+        DefaultDirName={autopf}\\#{inno(config.name)}
+        DefaultGroupName=#{inno(config.name)}
+        OutputDir=#{inno(output)}
+        OutputBaseFilename=#{inno(output_name)}
+        SetupIconFile=#{inno(config.icon_path(@project, platform))}
+        UninstallDisplayIcon={app}\\app.ico
+        Compression=lzma2
+        SolidCompression=yes
+        WizardStyle=modern
+        ArchitecturesAllowed=#{architectures}
+        ArchitecturesInstallIn64BitMode=#{architectures}
+
+        [Files]
+        Source: "#{inno(File.join(bundle, "*"))}"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
+
+        [Icons]
+        Name: "{autoprograms}\\#{inno(config.name)}"; Filename: "{app}\\run.cmd"; WorkingDir: "{app}"; IconFilename: "{app}\\app.ico"
+        Name: "{autodesktop}\\#{inno(config.name)}"; Filename: "{app}\\run.cmd"; WorkingDir: "{app}"; IconFilename: "{app}\\app.ico"
+      ISS
+    end
+
+    def gzip_tar(output, root, entries)
+      tar_path = "#{output}.tar-#{Process.pid}"
+      File.open(tar_path, "wb") do |file|
+        Gem::Package::TarWriter.new(file) do |tar|
+          entries.each { |entry| add_tar_entry(tar, root, File.join(root, entry)) }
+        end
+      end
+      Zlib::GzipWriter.open(output) do |gzip|
+        File.open(tar_path, "rb") { |tar| IO.copy_stream(tar, gzip) }
+      end
+    ensure
+      FileUtils.rm_f(tar_path) if tar_path
+    end
+
+    def add_tar_entry(tar, root, path)
+      relative = path.delete_prefix("#{root}#{File::SEPARATOR}").tr(File::SEPARATOR, "/")
+      name = "./#{relative}"
+      stat = File.lstat(path)
+      if stat.directory?
+        tar.mkdir(name, stat.mode & 0o777)
+        Dir.children(path).sort.each { |child| add_tar_entry(tar, root, File.join(path, child)) }
+      elsif stat.symlink?
+        tar.add_symlink(name, File.readlink(path), stat.mode & 0o777)
+      elsif stat.file?
+        tar.add_file(name, stat.mode & 0o777) do |target|
+          File.open(path, "rb") { |source| IO.copy_stream(source, target) }
+        end
+      else
+        raise ArgumentError, "unsupported file in distribution payload: #{path}"
+      end
+    end
+
+    def write_ar(output, files)
+      File.open(output, "wb", 0o644) do |archive|
+        archive.write("!<arch>\n")
+        files.each do |path|
+          size = File.size(path)
+          name = "#{File.basename(path)}/"
+          header = format("%-16s%-12d%-6d%-6d%-8s%-10d`\n",
+                          name, 0, 0, 0, "100644", size)
+          raise ArgumentError, "invalid Debian archive header" unless header.bytesize == 60
+
+          archive.write(header)
+          File.open(path, "rb") { |file| IO.copy_stream(file, archive) }
+          archive.write("\n") if size.odd?
+        end
+      end
+    end
+
+    def command!(*names, hint:)
+      candidates = names.dup
+      if platform.windows?
+        extensions = @environment.fetch("PATHEXT", ".EXE;.CMD;.BAT").split(";")
+        candidates += names.flat_map { |name| extensions.map { |extension| "#{name}#{extension}" } }
+      end
+      @environment.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |directory|
+        candidates.each do |name|
+          path = File.join(directory, name)
+          return path if File.file?(path) && File.executable?(path)
+        end
+      end
+      if platform.windows?
+        [@environment["ProgramFiles(x86)"], @environment["ProgramFiles"]].compact.each do |root|
+          path = File.join(root, "Inno Setup 6", "ISCC.exe")
+          return path if File.file?(path)
+        end
+      end
+      raise ArgumentError, "distribution packaging requires #{names.join(' or ')}; #{hint}"
+    end
+
+    def run!(arguments, timeout:)
+      result = Command.run(arguments, timeout:, max_output_bytes: 8_000_000)
+      return result if result.success?
+
+      details = [result.stdout, result.stderr].reject(&:empty?).join("\n").strip
+      message = "distribution command failed (#{File.basename(arguments.first)}), exit #{result.exitstatus}"
+      raise ArgumentError, details.empty? ? message : "#{message}:\n#{details}"
+    rescue CommandTimeout, CommandOutputLimit => error
+      raise ArgumentError, error.message
+    end
+
+    def safe_filename(value) = value.gsub(/[\\\/:*?"<>|]/, "-")
+    def rpm_escape(value) = value.to_s.gsub("%", "%%")
+    def inno(value) = value.to_s.gsub("{", "{{").gsub('"', '""')
+    def deb_architecture = platform.arch == :arm64 ? "arm64" : "amd64"
+    def rpm_architecture = platform.arch == :arm64 ? "aarch64" : "x86_64"
+    def tree_bytes(root) = Dir[File.join(root, "**", "*")].sum { |path| File.file?(path) ? File.size(path) : 0 }
+  end
+end