zui 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ae2e4258c9dcaea2c3717920199c8cca6a5105b891f2fd3940b2b4843210999
-  data.tar.gz: b8185c66c6bef8b2a447819f6a474521bf7773246bdd50e7dcc2e5618efd8837
+  metadata.gz: 00eeeccbcd56e9deb1c78c93b913ee8e137af12cbd00dab4cc8ba3f4c13e3b9b
+  data.tar.gz: dd8e6f8d38493ca5e060be45adf6ffdc7584adac357a4789d59dbdb11bcdc8d5
 SHA512:
-  metadata.gz: c17ff8fbdd6c51cc13f924d123ec8a72f789a096dbf965e3cff6b30d7423c29f23090e962422009091e46e4f8889a358043cf3bbe4d07267d103b228d8a2baa7
-  data.tar.gz: c966b6a472b0b43e3e7eed8f607b17b271e3fda93cb7e23a619a5367a1c320b6e708b7a9f53e26b179e25c69e8e29f6091f41fa3c9e31f2079cd3cfffd51b41e
+  metadata.gz: 6bdcbd3b815283726e6854913ff620209452d989080a501dc2c717945a76ecd957e3cda6ddaa11e6ff0ca9c32d960eb07c0832b0012afebc4ca2e0f92c6a2b2c
+  data.tar.gz: da469681842aed14ff1176f66bf5b31767802a3097a9d6741560f594dbca66ae7af39a7d32a2d7b2c9931cd7af9adf9a796a083d224bcfc95445cfbc9b9c55a8

data/README.md

@@ -1,8 +1,8 @@
 # Zui
 
-Zui is a platform-neutral Ruby framework for native desktop interfaces powered by Qt and QML.
-Ruby owns the application, component tree, state, events, bindings, animation descriptions, and
-business logic. QML is the rendering backend, not application code.
+Zui builds beautiful native desktop applications in pure Ruby, with first-class UI, state,
+events, bindings, animation, media, GPU effects, 3D, and application logic. Applications are
+Ruby and assets—there is no application UI language to learn alongside Ruby.
 
 This repository is the reusable core. Distribution integrations live at its edges:
 
@@ -38,6 +38,7 @@ end
 
 ```bash
 gem install zui
+zui doctor --fix
 zui new telemetry-console
 cd telemetry-console
 zui run main.rb
@@ -48,23 +49,32 @@ Build and install the gem directly from a checkout:
 
 ```bash
 gem build zui.gemspec
-gem install ./zui-0.0.1.gem
+gem install ./zui-0.0.2.gem
 ```
 
-`zui run` uses the bundled host for supported release targets. If a matching host is not
-bundled, Zui builds and caches it from the checked-in C++ source with CMake and Qt 6.8 or newer.
+`zui doctor --fix` is the one-time setup for each Zui version and platform. It downloads the
+matching versioned client from GitHub Releases, verifies its SHA-256 checksum and manifest, and
+installs it in the native user cache. `zui configure` performs the same explicit setup operation.
+The prebuilt client is never packaged in or downloaded from the RubyGem. It contains the native
+host and its Qt/QML engine libraries—not the developer's application, Ruby source, or the Zui
+Ruby/QML framework. Setup never changes the global shell environment; `zui run` supplies the
+client paths only to the child application.
 
-`zui bundle` produces an application directory on Linux and Windows and a standard `.app` bundle
-on macOS. Each package includes the application, Zui Ruby runtime, QML renderer, component catalog,
-theme, controls, and native host. Ruby and the required Qt runtime libraries must be available on
-the destination machine; native installers can add them with the platform's normal deployment
-tools.
+Developers install Ruby and the `zui` gem. They do not install CMake, a C++ compiler, or Qt. Those
+tools are used only by Zui's release CI to produce the platform clients.
+
+`zui bundle` uses a platform template to produce an application directory on Linux and Windows or
+a standard `.app` on macOS. The package combines the application's Ruby/assets, the Zui framework
+runtime and catalog, and a private copy of the configured native Qt/QML client. No system Qt
+installation is used by the finished bundle. The current bundle format expects Ruby 3.1 or newer
+on the destination and supports `ZUI_RUBY` when an installer provides a private Ruby executable.
 
 See [Platform support](docs/platforms.md) for host requirements and bundle layouts.
 
-Zui has no separate validation command. `run` opens the app directly, and
-`bundle` packages the project directly. Ruby, DSL, protocol, resource, and QML
-errors are reported by the operation that actually encounters them.
+`zui doctor` is read-only: it reports platform, Ruby, client, run, and bundle readiness. Add
+`--fix` to download and install the missing client from GitHub Releases. Zui has no separate
+validation command; Ruby, DSL, protocol, resource, and QML errors are reported by the operation
+that encounters them.
 
 ## Reusable application UI
 

data/lib/zui/cli.rb

@@ -5,7 +5,7 @@ require "rbconfig"
 
 module Zui
   class CLI
-    USAGE = "Usage: zui <new NAME|run FILE|bundle [DIRECTORY]|doctor|version>"
+    USAGE = "Usage: zui <new NAME|configure|doctor [--fix]|run FILE|bundle [DIRECTORY]|version>"
 
     def self.run(arguments, out: $stdout, err: $stderr)
       new(out:, err:).run(arguments.dup)
@@ -20,6 +20,7 @@ module Zui
       command = arguments.shift
       case command
       when "new" then new_project(arguments)
+      when "configure" then configure(arguments)
       when "run" then run_file(arguments)
       when "bundle" then bundle_project(arguments)
       when "doctor" then doctor(arguments)
@@ -63,15 +64,44 @@ module Zui
     end
 
     def doctor(arguments)
-      raise ArgumentError, "doctor accepts no arguments" unless arguments.empty?
+      fix = arguments.delete("--fix")
+      raise ArgumentError, "doctor accepts only --fix" unless arguments.empty?
       platform = Platform.current
-      host = Host.new(platform:)
       @out.puts("Zui #{VERSION}")
       @out.puts("Platform: #{platform.id}#{platform.supported? ? '' : ' (unsupported)'}")
       @out.puts("Ruby: #{RbConfig.ruby} (#{RUBY_VERSION})")
-      @out.puts("Host: #{host.executable(build: false) || 'not built'}") if platform.supported?
-      @out.puts("Qt build requirements: #{host.platform_help}") if platform.supported? && !host.available?
-      platform.supported? ? 0 : 1
+      return 1 unless platform.supported?
+
+      client = Client.new(platform:)
+      if client.configured?
+        report_ready(client)
+        0
+      elsif fix
+        @out.puts("Repair: downloading the verified native client from GitHub Releases...")
+        client.configure!
+        report_ready(client)
+        0
+      else
+        @out.puts("Client: not configured")
+        @out.puts("Run `zui doctor --fix` to install the native client and bundle support.")
+        1
+      end
+    end
+
+    def configure(arguments)
+      raise ArgumentError, "configure accepts no arguments" unless arguments.empty?
+      platform = Platform.current.assert_supported!
+      client = Client.new(platform:)
+      @out.puts("Configuring Zui #{VERSION} for #{platform.id}...")
+      client.configure!
+      report_ready(client)
+      0
+    end
+
+    def report_ready(client)
+      @out.puts("Client: #{client.root}")
+      @out.puts("Run: ready")
+      @out.puts("Bundle: ready")
     end
 
     def option_value(arguments, name)

data/lib/zui/client.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "net/http"
+require "openssl"
+require "tmpdir"
+require "timeout"
+require "uri"
+require "zlib"
+require "rubygems/package"
+
+module Zui
+  class Client
+    FORMAT = 1
+    MAX_ARCHIVE_BYTES = 1_073_741_824
+    MAX_EXPANDED_BYTES = 2_147_483_648
+    MAX_ENTRIES = 100_000
+    REDIRECT_LIMIT = 5
+
+    attr_reader :platform, :version
+
+    def initialize(platform: Platform.current, version: VERSION, environment: ENV,
+                   cache_root: nil, release_base_url: nil, downloader: nil)
+      @platform = platform.assert_supported!
+      @version = version.to_s
+      @environment = environment
+      @cache_root = cache_root
+      @release_base_url = release_base_url
+      @downloader = downloader || method(:download)
+    end
+
+    def root
+      override = @environment["ZUI_CLIENT_ROOT"]
+      return File.expand_path(override) if override && !override.empty?
+
+      File.join(cache_root, "zui", "clients", version, platform.id)
+    end
+
+    def configured?
+      validate!(root)
+      true
+    rescue ArgumentError, Errno::ENOENT
+      false
+    end
+
+    def configure!
+      return root if configured?
+      raise ArgumentError, "ZUI_CLIENT_ROOT is not a valid configured client: #{root}" if client_root_override?
+
+      FileUtils.mkdir_p(File.dirname(root))
+      File.open("#{root}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        return root if configured?
+
+        install_download!
+      end
+      root
+    end
+
+    def executable
+      manifest = validate!(root)
+      File.join(root, manifest.fetch("executable"))
+    end
+
+    def executable_relative_path
+      validate!(root).fetch("executable")
+    end
+
+    def environment_entries
+      manifest = validate!(root)
+      manifest.fetch("environment", {}).transform_values do |paths|
+        Array(paths).map { |path| safe_manifest_path!(path, "client environment path") }
+      end
+    end
+
+    def environment(base = ENV.to_h, client_root: root)
+      environment_entries.each_with_object(base.to_h.dup) do |(name, paths), result|
+        unless name.match?(/\A[A-Z][A-Z0-9_]*\z/)
+          raise ArgumentError, "invalid environment variable in Zui client: #{name.inspect}"
+        end
+
+        resolved = paths.map { |path| File.join(client_root, path) }
+        previous = result[name]
+        resolved << previous unless previous.nil? || previous.empty?
+        result[name] = resolved.join(File::PATH_SEPARATOR)
+      end
+    end
+
+    def copy_to(destination)
+      manifest = validate!(root)
+      raise ArgumentError, "client destination already exists: #{destination}" if File.exist?(destination)
+
+      created = true
+      FileUtils.mkdir_p(destination)
+      FileUtils.cp_r(Dir.children(root).map { |entry| File.join(root, entry) }, destination)
+      validate!(destination)
+      manifest
+    rescue StandardError
+      FileUtils.remove_entry(destination) if created && destination && File.exist?(destination)
+      raise
+    end
+
+    def manifest
+      validate!(root)
+    end
+
+    def archive_name = "zui-client-#{platform.id}.tar.gz"
+
+    def archive_url
+      override = @environment["ZUI_CLIENT_ARCHIVE"]
+      return File.expand_path(override) if override && !override.empty?
+
+      URI.join("#{release_base_url}/", archive_name)
+    end
+
+    def checksum_url
+      override = @environment["ZUI_CLIENT_CHECKSUM"]
+      return File.expand_path(override) if override && !override.empty?
+
+      source = archive_url
+      source.is_a?(URI) ? URI("#{source}.sha256") : "#{source}.sha256"
+    end
+
+    private
+
+    def install_download!
+      Dir.mktmpdir(".zui-client-", File.dirname(root)) do |temporary|
+        archive = File.join(temporary, archive_name)
+        checksum = "#{archive}.sha256"
+        @downloader.call(archive_url, archive)
+        @downloader.call(checksum_url, checksum)
+        verify_checksum!(archive, checksum)
+
+        staged = File.join(temporary, "client")
+        FileUtils.mkdir_p(staged)
+        extract!(archive, staged)
+        validate!(staged)
+
+        installed = "#{root}.install-#{Process.pid}-#{rand(1_000_000)}"
+        File.rename(staged, installed)
+        if File.exist?(root)
+          invalid = "#{root}.invalid-#{Time.now.to_i}-#{Process.pid}"
+          File.rename(root, invalid)
+        end
+        File.rename(installed, root)
+      ensure
+        FileUtils.remove_entry(installed) if installed && File.exist?(installed)
+      end
+      validate!(root)
+      root
+    end
+
+    def validate!(directory)
+      manifest_path = File.join(directory, "client.json")
+      raise ArgumentError, "Zui client manifest not found: #{manifest_path}" unless File.file?(manifest_path)
+      raise ArgumentError, "Zui client manifest is too large" if File.size(manifest_path) > 65_536
+
+      manifest = JSON.parse(File.read(manifest_path))
+      raise ArgumentError, "invalid Zui client manifest root" unless manifest.is_a?(Hash)
+      expected = {
+        "format" => FORMAT,
+        "framework" => "zui",
+        "client_version" => version,
+        "platform" => platform.id
+      }
+      expected.each do |key, value|
+        actual = manifest[key]
+        raise ArgumentError, "invalid Zui client #{key}: expected #{value.inspect}, got #{actual.inspect}" unless actual == value
+      end
+      raise ArgumentError, "Zui client is not bundle capable" unless manifest["bundle_capable"] == true
+      unless manifest["payload"] == %w[native-host qt-engine]
+        raise ArgumentError, "invalid Zui client payload: expected native host and Qt engine only"
+      end
+
+      required_paths = manifest["required_paths"]
+      unless required_paths.is_a?(Array) && !required_paths.empty? &&
+             required_paths.all? { |path| path.is_a?(String) }
+        raise ArgumentError, "invalid Zui client required paths"
+      end
+      required_paths.each do |path|
+        relative_path = safe_manifest_path!(path, "client required path")
+        resolved_path = File.join(directory, relative_path)
+        raise ArgumentError, "Zui client required path is missing: #{resolved_path}" unless File.exist?(resolved_path)
+      end
+
+      relative = safe_manifest_path!(manifest["executable"], "client executable")
+      executable = File.join(directory, relative)
+      unless File.file?(executable) && executable_for_target?(executable)
+        raise ArgumentError, "Zui client executable is missing or not executable: #{executable}"
+      end
+
+      client_environment = manifest.fetch("environment", {})
+      raise ArgumentError, "invalid Zui client environment" unless client_environment.is_a?(Hash)
+      client_environment.each do |name, paths|
+        unless name.is_a?(String) && name.match?(/\A[A-Z][A-Z0-9_]*\z/)
+          raise ArgumentError, "invalid client environment entry: #{name.inspect}"
+        end
+        unless paths.is_a?(Array) && !paths.empty? && paths.all? { |path| path.is_a?(String) }
+          raise ArgumentError, "invalid client environment paths for #{name}"
+        end
+        paths.each do |path|
+          relative_path = safe_manifest_path!(path, "client environment path")
+          resolved_path = File.join(directory, relative_path)
+          raise ArgumentError, "Zui client environment path is missing: #{resolved_path}" unless File.exist?(resolved_path)
+        end
+      end
+      manifest
+    rescue JSON::ParserError => error
+      raise ArgumentError, "invalid Zui client manifest: #{error.message}"
+    end
+
+    def executable_for_target?(path)
+      # Windows cannot represent the POSIX executable bit when validating a
+      # Linux or macOS archive. Native POSIX clients still require that bit.
+      platform.windows? || Gem.win_platform? || File.executable?(path)
+    end
+
+    def verify_checksum!(archive, checksum_file)
+      expected = File.read(checksum_file, 4096)[/\A\s*([0-9a-fA-F]{64})(?:\s|\z)/, 1]
+      raise ArgumentError, "invalid Zui client checksum file" unless expected
+
+      actual = Digest::SHA256.file(archive).hexdigest
+      raise ArgumentError, "Zui client checksum mismatch" unless actual.casecmp?(expected)
+    end
+
+    def extract!(archive, destination)
+      count = 0
+      expanded = 0
+      Zlib::GzipReader.open(archive) do |gzip|
+        Gem::Package::TarReader.new(gzip) do |tar|
+          tar.each do |entry|
+            count += 1
+            raise ArgumentError, "Zui client archive contains too many files" if count > MAX_ENTRIES
+
+            relative = safe_relative_path!(entry.full_name, "archive entry")
+            target = File.join(destination, relative)
+            if entry.directory?
+              FileUtils.mkdir_p(target)
+            elsif entry.file?
+              expanded += entry.header.size
+              raise ArgumentError, "Zui client archive expands beyond the safety limit" if expanded > MAX_EXPANDED_BYTES
+
+              FileUtils.mkdir_p(File.dirname(target))
+              File.open(target, "wb", entry.header.mode & 0o111 == 0 ? 0o644 : 0o755) do |file|
+                IO.copy_stream(entry, file)
+              end
+            else
+              raise ArgumentError, "Zui client archive contains an unsupported link or special file: #{entry.full_name}"
+            end
+          end
+        end
+      end
+    rescue Zlib::GzipFile::Error, Gem::Package::TarInvalidError => error
+      raise ArgumentError, "invalid Zui client archive: #{error.message}"
+    end
+
+    def download(source, destination, redirects = REDIRECT_LIMIT)
+      if source.is_a?(String) && File.file?(source)
+        FileUtils.cp(source, destination)
+        return destination
+      end
+      uri = source.is_a?(URI) ? source : URI(source.to_s)
+      if uri.scheme == "file"
+        FileUtils.cp(URI::DEFAULT_PARSER.unescape(uri.path), destination)
+        return destination
+      end
+      raise ArgumentError, "Zui client download must use HTTPS" unless uri.scheme == "https"
+      raise ArgumentError, "too many Zui client download redirects" if redirects.negative?
+
+      http = Net::HTTP.new(uri.host, uri.port, :ENV)
+      http.use_ssl = true
+      http.open_timeout = 20
+      http.read_timeout = 120
+      http.write_timeout = 120 if http.respond_to?(:write_timeout=)
+      http.start do
+        http.request(Net::HTTP::Get.new(uri.request_uri)) do |response|
+          case response
+          when Net::HTTPSuccess
+            written = 0
+            File.open(destination, "wb") do |file|
+              response.read_body do |chunk|
+                written += chunk.bytesize
+                raise ArgumentError, "Zui client download exceeds the safety limit" if written > MAX_ARCHIVE_BYTES
+                file.write(chunk)
+              end
+            end
+          when Net::HTTPRedirection
+            location = response["location"] || raise(ArgumentError, "Zui client redirect has no location")
+            return download(URI.join(uri, location), destination, redirects - 1)
+          else
+            raise ArgumentError, "Zui client download failed: HTTP #{response.code}"
+          end
+        end
+      end
+      destination
+    rescue URI::InvalidURIError => error
+      raise ArgumentError, "invalid Zui client URL: #{error.message}"
+    rescue Timeout::Error, SocketError, OpenSSL::SSL::SSLError => error
+      raise ArgumentError, "Zui client download failed: #{error.class}: #{error.message}"
+    end
+
+    def safe_relative_path!(value, label)
+      path = value.to_s
+      if path.empty? || path.include?("\\") || path.match?(/[[:cntrl:]]/) || path.start_with?("/") ||
+         path.match?(/\A[A-Za-z]:/) ||
+         path.split("/").any? { |part| part.empty? || part == "." || part == ".." }
+        raise ArgumentError, "unsafe #{label}: #{value.inspect}"
+      end
+      path
+    end
+
+    def safe_manifest_path!(value, label)
+      path = safe_relative_path!(value, label)
+      unless path.match?(/\A[A-Za-z0-9._+ -]+(?:\/[A-Za-z0-9._+ -]+)*\z/)
+        raise ArgumentError, "unsafe #{label}: #{value.inspect}"
+      end
+      path
+    end
+
+    def release_base_url
+      @release_base_url || @environment["ZUI_CLIENT_BASE_URL"] ||
+        "https://github.com/AdamMusa/zui/releases/download/v#{version}"
+    end
+
+    def cache_root
+      return File.expand_path(@cache_root) if @cache_root
+
+      override = @environment["ZUI_CACHE_HOME"]
+      return File.expand_path(override) if override && !override.empty?
+
+      home = @environment["HOME"] || @environment["USERPROFILE"] || Dir.home
+      if platform.windows?
+        @environment["LOCALAPPDATA"] || @environment["APPDATA"] || File.join(home, "AppData", "Local")
+      elsif platform.macos?
+        File.join(home, "Library", "Caches")
+      else
+        @environment["XDG_CACHE_HOME"] || File.join(home, ".cache")
+      end
+    end
+
+    def client_root_override?
+      value = @environment["ZUI_CLIENT_ROOT"]
+      value && !value.empty?
+    end
+
+  end
+end

data/lib/zui/distribution.rb

@@ -7,20 +7,25 @@ module Zui
   class Distribution
     attr_reader :platform
 
-    def initialize(host: Host.new, platform: Platform.current, framework_root: FRAMEWORK_ROOT)
-      @host = host
+    def initialize(client: nil, platform: Platform.current, framework_root: FRAMEWORK_ROOT)
       @platform = platform.assert_supported!
+      @client = client || Client.new(platform: @platform)
       @framework_root = framework_root
     end
 
     def bundle(source, name: nil, destination: nil)
+      created = false
       project = File.expand_path(source)
       raise ArgumentError, "project directory not found: #{project}" unless File.directory?(project)
       raise ArgumentError, "main.rb not found: #{project}" unless File.file?(File.join(project, "main.rb"))
+      unless @client.configured?
+        raise ArgumentError, "Zui is not configured for #{platform.id}; run `zui doctor --fix` before bundling"
+      end
       app_name = name || titleize(File.basename(project))
       destination ||= default_destination(project, app_name)
       destination = File.expand_path(destination)
       raise ArgumentError, "bundle destination already exists: #{destination}" if File.exist?(destination)
+      created = true
 
       case platform.os
       when :linux then bundle_linux(project, destination, app_name)
@@ -29,19 +34,18 @@ module Zui
       end
       destination
     rescue StandardError
-      FileUtils.remove_entry(destination) if destination && File.exist?(destination)
+      FileUtils.remove_entry(destination) if created && destination && File.exist?(destination)
       raise
     end
 
     private
 
     def bundle_linux(project, destination, app_name)
-      FileUtils.mkdir_p([File.join(destination, "app"), File.join(destination, "bin"),
+      FileUtils.mkdir_p([File.join(destination, "app"),
                          File.join(destination, "runtime"), File.join(destination, "share", "applications")])
       install_application(project, File.join(destination, "app"))
       install_runtime(File.join(destination, "runtime"))
-      FileUtils.cp(@host.executable, File.join(destination, "bin", "zui-host"))
-      FileUtils.chmod(0o755, File.join(destination, "bin", "zui-host"))
+      @client.copy_to(File.join(destination, "runtime", "native"))
       write_linux_launcher(destination, app_name)
       desktop_name = "#{slug(app_name)}.desktop"
       File.write(File.join(destination, "share", "applications", desktop_name), <<~DESKTOP)
@@ -62,8 +66,7 @@ module Zui
       FileUtils.mkdir_p([macos, File.join(resources, "app"), File.join(resources, "runtime")])
       install_application(project, File.join(resources, "app"))
       install_runtime(File.join(resources, "runtime"))
-      FileUtils.cp(@host.executable, File.join(macos, "zui-host"))
-      FileUtils.chmod(0o755, File.join(macos, "zui-host"))
+      @client.copy_to(File.join(resources, "runtime", "native"))
       File.write(File.join(macos, "run"), macos_launcher(app_name))
       FileUtils.chmod(0o755, File.join(macos, "run"))
       File.write(File.join(contents, "Info.plist"), info_plist(app_name))
@@ -71,11 +74,11 @@ module Zui
     end
 
     def bundle_windows(project, destination, app_name)
-      FileUtils.mkdir_p([File.join(destination, "app"), File.join(destination, "bin"),
+      FileUtils.mkdir_p([File.join(destination, "app"),
                          File.join(destination, "runtime")])
       install_application(project, File.join(destination, "app"))
       install_runtime(File.join(destination, "runtime"))
-      FileUtils.cp(@host.executable, File.join(destination, "bin", "zui-host.exe"))
+      @client.copy_to(File.join(destination, "runtime", "native"))
       File.write(File.join(destination, "run.rb"), windows_ruby_launcher(app_name))
       File.write(File.join(destination, "run.cmd"), windows_command_launcher)
       write_manifest(destination, app_name)
@@ -93,7 +96,11 @@ module Zui
       Runtime.install_qml(File.join(destination, "qml"), framework_root: @framework_root)
       FileUtils.mkdir_p(File.join(destination, "lib"))
       FileUtils.cp(File.join(@framework_root, "lib", "zui.rb"), File.join(destination, "lib", "zui.rb"))
-      FileUtils.cp_r(File.join(@framework_root, "lib", "zui"), File.join(destination, "lib", "zui"))
+      source = File.join(@framework_root, "lib", "zui")
+      target = File.join(destination, "lib", "zui")
+      FileUtils.mkdir_p(target)
+      entries = Dir.children(source).reject { |entry| %w[client_builder.rb client_packager.rb].include?(entry) }
+      FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, target) unless entries.empty?
     end
 
     def write_linux_launcher(destination, app_name)
@@ -101,8 +108,10 @@ module Zui
         #!/bin/sh
         set -eu
         bundle_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+        native_dir="$bundle_dir/runtime/native"
+        #{posix_client_environment}
         ruby_command=${ZUI_RUBY:-ruby}
-        exec "$bundle_dir/bin/zui-host" \
+        exec "$native_dir/#{@client.executable_relative_path}" \
           --qml-root "$bundle_dir/runtime/qml" \
           --project "$bundle_dir/app" \
           --program "$bundle_dir/app/main.rb" \
@@ -119,8 +128,10 @@ module Zui
         set -eu
         contents=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
         resources="$contents/Resources"
+        native_dir="$resources/runtime/native"
+        #{posix_client_environment}
         ruby_command=${ZUI_RUBY:-ruby}
-        exec "$contents/MacOS/zui-host" \
+        exec "$native_dir/#{@client.executable_relative_path}" \
           --qml-root "$resources/runtime/qml" \
           --project "$resources/app" \
           --program "$resources/app/main.rb" \
@@ -137,8 +148,11 @@ module Zui
         require "rbconfig"
 
         bundle_dir = File.expand_path(__dir__)
+        native_dir = File.join(bundle_dir, "runtime", "native")
+        environment = {}
+        #{windows_environment_builder}
         arguments = [
-          File.join(bundle_dir, "bin", "zui-host.exe"),
+          File.join(native_dir, #{@client.executable_relative_path.dump}),
           "--qml-root", File.join(bundle_dir, "runtime", "qml"),
           "--project", File.join(bundle_dir, "app"),
           "--program", File.join(bundle_dir, "app", "main.rb"),
@@ -146,7 +160,7 @@ module Zui
           "--load-path", File.join(bundle_dir, "runtime", "lib"),
           "--name", #{app_name.to_s.dump}
         ]
-        exec(*arguments)
+        exec(environment, *arguments)
       RUBY
     end
 
@@ -183,7 +197,7 @@ module Zui
       File.write(File.join(directory, "zui-bundle.json"), JSON.pretty_generate(
         "format" => 1, "framework" => "zui", "version" => VERSION,
         "platform" => platform.os.to_s, "architecture" => platform.arch.to_s,
-        "name" => app_name
+        "name" => app_name, "client_version" => @client.manifest.fetch("client_version")
       ))
     end
 
@@ -196,5 +210,28 @@ module Zui
     def slug(value) = value.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
     def shell_quote(value) = "'#{value.to_s.gsub("'", %q('"'"'))}'"
     def xml_escape(value) = value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+
+    def posix_client_environment
+      @client.environment_entries.map do |name, paths|
+        value = paths.map { |path| "$native_dir/#{path}" }.join(":")
+        <<~SH.chomp
+          zui_environment="#{value}"
+          [ -z "${#{name}:-}" ] || zui_environment="$zui_environment:${#{name}}"
+          export #{name}="$zui_environment"
+        SH
+      end.join("\n")
+    end
+
+    def windows_client_environment = @client.environment_entries
+
+    def windows_environment_builder
+      @client.environment_entries.keys.map do |name|
+        <<~RUBY.chomp
+          values = #{windows_client_environment.fetch(name).inspect}.map { |path| File.join(native_dir, path) }
+          values << ENV[#{name.dump}] unless ENV[#{name.dump}].nil? || ENV[#{name.dump}].empty?
+          environment[#{name.dump}] = values.join(File::PATH_SEPARATOR)
+        RUBY
+      end.join("\n")
+    end
   end
 end

data/lib/zui/generator.rb

@@ -69,6 +69,7 @@ module Zui
         A native Linux, macOS, and Windows desktop application written in Ruby with Zui.
 
         ```bash
+        zui doctor --fix # once for each Zui version
         zui run main.rb
         zui bundle
         ```

data/lib/zui/host.rb

@@ -1,123 +1,45 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "tmpdir"
-
 module Zui
   class Host
-    attr_reader :platform
+    attr_reader :client, :platform
 
-    def initialize(platform: Platform.current, framework_root: FRAMEWORK_ROOT, environment: ENV)
+    def initialize(platform: Platform.current, environment: ENV, client: nil)
       @platform = platform.assert_supported!
-      @framework_root = framework_root
       @environment = environment
+      @client = client || Client.new(platform:, environment:)
     end
 
-    def executable(build: true)
+    def executable
       override = @environment["ZUI_HOST"]
       return checked_executable(override) if override && !override.empty?
-      return bundled if File.executable?(bundled)
-      return cached if File.executable?(cached)
-      return nil unless build
+      return client.executable if client.configured?
 
-      build!(cached)
+      raise ArgumentError, "Zui is not configured for #{platform.id}; run `zui doctor --fix`"
     end
 
-    def available? = !executable(build: false).nil?
-
-    def build!(destination = cached)
-      cmake = find_command("cmake")
-      raise ArgumentError, platform_help unless cmake
-
-      FileUtils.mkdir_p(File.dirname(destination))
-      Dir.mktmpdir("zui-host-build-") do |build_dir|
-        configure = Command.run([
-          cmake, "-S", File.join(@framework_root, "native"), "-B", build_dir,
-          "-DCMAKE_BUILD_TYPE=Release"
-        ], timeout: 180, max_output_bytes: 4_194_304)
-        raise ArgumentError, "Zui host configuration failed:\n#{configure.stderr}" unless configure.success?
-
-        compile = Command.run([cmake, "--build", build_dir, "--config", "Release", "--parallel"],
-                              timeout: 600, max_output_bytes: 8_388_608)
-        raise ArgumentError, "Zui host build failed:\n#{compile.stderr}" unless compile.success?
-
-        built = locate_build(build_dir)
-        raise ArgumentError, "Zui host build produced no executable" unless built
-        temporary = "#{destination}.install-#{Process.pid}"
-        FileUtils.cp(built, temporary)
-        FileUtils.chmod(0o755, temporary)
-        File.rename(temporary, destination)
-      ensure
-        FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
-      end
-      destination
-    end
+    def available?
+      override = @environment["ZUI_HOST"]
+      return File.executable?(File.expand_path(override)) if override && !override.empty?
 
-    def platform_help
-      if platform.macos?
-        "building Zui on macOS requires CMake and Qt 6 (for example: brew install cmake qt)"
-      elsif platform.windows?
-        "building Zui on Windows requires CMake, Qt 6, and a C++17 toolchain (Visual Studio Build Tools or LLVM/MinGW)"
-      else
-        "building Zui on Linux requires CMake, a C++17 compiler, and Qt 6 Core/Gui/Qml/Quick development packages"
-      end
+      client.configured?
     end
 
-    private
-
-    def bundled
-      File.join(@framework_root, "vendor", "host", platform.id, executable_name)
-    end
+    def configure! = client.configure!
 
-    def cached
-      cache_root = @environment["XDG_CACHE_HOME"]
-      cache_root = default_cache_root if cache_root.nil? || cache_root.empty?
-      File.join(cache_root, "zui", "host", VERSION, platform.id, executable_name)
-    end
+    def environment(base = ENV.to_h)
+      override = @environment["ZUI_HOST"]
+      return base.to_h.dup if override && !override.empty?
 
-    def default_cache_root
-      home = @environment["HOME"] || @environment["USERPROFILE"] || Dir.home
-      if platform.windows?
-        @environment["LOCALAPPDATA"] || @environment["APPDATA"] || File.join(home, "AppData", "Local")
-      elsif platform.macos?
-        File.join(home, "Library", "Caches")
-      else
-        File.join(home, ".cache")
-      end
+      client.environment(base)
     end
 
-    def executable_name = platform.os == :windows ? "zui-host.exe" : "zui-host"
+    private
 
     def checked_executable(path)
       expanded = File.expand_path(path)
       raise ArgumentError, "ZUI_HOST is not executable: #{expanded}" unless File.executable?(expanded)
       expanded
     end
-
-    def find_command(name)
-      @environment.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |directory|
-        command_names(name).each do |command_name|
-          path = File.join(directory, command_name)
-          return path if File.executable?(path) && !File.directory?(path)
-        end
-      end
-      nil
-    end
-
-    def command_names(name)
-      return [name] unless platform.windows? && File.extname(name).empty?
-
-      extensions = @environment.fetch("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";")
-      [name] + extensions.flat_map { |extension| ["#{name}#{extension.downcase}", "#{name}#{extension.upcase}"] }.uniq
-    end
-
-    def locate_build(build_dir)
-      candidates = [
-        File.join(build_dir, executable_name),
-        File.join(build_dir, "Release", executable_name),
-        File.join(build_dir, "zui-host.app", "Contents", "MacOS", "zui-host")
-      ]
-      candidates.find { |path| File.executable?(path) }
-    end
   end
 end

data/lib/zui/runner.rb

@@ -24,7 +24,7 @@ module Zui
         "--load-path", File.join(@framework_root, "lib"),
         "--name", name || project_name(project)
       ]
-      system(environment, *arguments)
+      system(@host.environment(environment), *arguments)
       $?&.exitstatus || 1
     end
 

data/lib/zui.rb

@@ -14,13 +14,14 @@ require_relative "zui/application"
 require_relative "zui/source_bundle"
 require_relative "zui/platform"
 require_relative "zui/runtime"
+require_relative "zui/client"
 require_relative "zui/host"
 require_relative "zui/runner"
 require_relative "zui/generator"
 require_relative "zui/distribution"
 
 module Zui
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
   FRAMEWORK_ROOT = File.expand_path("..", __dir__)
 
   def self.app(&definition)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zui
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Adam Moussa Ali
@@ -9,7 +9,8 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A platform-neutral Ruby UI framework powered by Qt and QML.
+description: First-class UI, state, events, animation, media, GPU effects, and 3D
+  for Ruby desktop applications.
 executables:
 - zui
 extensions: []
@@ -314,6 +315,7 @@ files:
 - lib/zui/application.rb
 - lib/zui/builder.rb
 - lib/zui/cli.rb
+- lib/zui/client.rb
 - lib/zui/command.rb
 - lib/zui/component_registry.rb
 - lib/zui/components.rb
@@ -329,15 +331,6 @@ files:
 - lib/zui/source_bundle.rb
 - lib/zui/state_store.rb
 - lib/zui/value.rb
-- native/CMakeLists.txt
-- native/ZuiClipboard.cpp
-- native/ZuiClipboard.h
-- native/ZuiProcess.cpp
-- native/ZuiProcess.h
-- native/main.cpp
-- vendor/host/linux-x86_64/PROVENANCE.md
-- vendor/host/linux-x86_64/zui-host
-- vendor/host/linux-x86_64/zui-host.sha256
 homepage: https://github.com/AdamMusa/zui
 licenses:
 - MIT
@@ -361,5 +354,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.18
 specification_version: 4
-summary: Build cross-platform native desktop applications in Ruby
+summary: Build beautiful native desktop applications in pure Ruby
 test_files: []

data/native/CMakeLists.txt

@@ -1,45 +0,0 @@
-cmake_minimum_required(VERSION 3.21)
-project(zui-host VERSION 0.1.0 LANGUAGES CXX)
-
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_AUTOMOC ON)
-
-find_package(Qt6 6.8 REQUIRED COMPONENTS
-  Core
-  Gui
-  Multimedia
-  Qml
-  Quick
-  QuickControls2
-  QuickVectorImage
-)
-find_package(Qt6 6.8 QUIET COMPONENTS WebEngineQuick)
-
-qt_add_executable(zui-host
-  main.cpp
-  ZuiClipboard.cpp
-  ZuiClipboard.h
-  ZuiProcess.cpp
-  ZuiProcess.h
-)
-
-target_link_libraries(zui-host PRIVATE
-  Qt6::Core
-  Qt6::Gui
-  Qt6::Multimedia
-  Qt6::Qml
-  Qt6::Quick
-  Qt6::QuickControls2
-  Qt6::QuickVectorImage
-)
-
-if(TARGET Qt6::WebEngineQuick)
-  target_link_libraries(zui-host PRIVATE Qt6::WebEngineQuick)
-  target_compile_definitions(zui-host PRIVATE ZUI_HAS_WEBENGINE=1)
-endif()
-
-install(TARGETS zui-host
-  BUNDLE DESTINATION .
-  RUNTIME DESTINATION bin
-)

data/native/ZuiClipboard.cpp

@@ -1,16 +0,0 @@
-#include "ZuiClipboard.h"
-
-#include <QGuiApplication>
-#include <QClipboard>
-
-ZuiClipboard::ZuiClipboard(QObject *parent) : QObject(parent) {
-  connect(QGuiApplication::clipboard(), &QClipboard::dataChanged, this, &ZuiClipboard::textChanged);
-}
-
-QString ZuiClipboard::text() const { return QGuiApplication::clipboard()->text(); }
-
-void ZuiClipboard::setText(const QString &text) {
-  if (this->text() == text)
-    return;
-  QGuiApplication::clipboard()->setText(text);
-}

data/native/ZuiClipboard.h

@@ -1,16 +0,0 @@
-#pragma once
-
-#include <QObject>
-
-class ZuiClipboard final : public QObject {
-  Q_OBJECT
-  Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
-
-public:
-  explicit ZuiClipboard(QObject *parent = nullptr);
-  QString text() const;
-  void setText(const QString &text);
-
-signals:
-  void textChanged();
-};

data/native/ZuiProcess.cpp

@@ -1,84 +0,0 @@
-#include "ZuiProcess.h"
-
-#include <QProcessEnvironment>
-#include <QTimer>
-
-ZuiProcess::ZuiProcess(QObject *parent) : QObject(parent) {
-  connect(&m_process, &QProcess::stateChanged, this, [this] { emit runningChanged(); });
-  connect(&m_process, &QProcess::readyReadStandardOutput, this, [this] {
-    m_stdoutBuffer += m_process.readAllStandardOutput();
-    consume(m_stdoutBuffer, false);
-  });
-  connect(&m_process, &QProcess::readyReadStandardError, this, [this] {
-    m_stderrBuffer += m_process.readAllStandardError();
-    consume(m_stderrBuffer, true);
-  });
-  connect(&m_process, &QProcess::errorOccurred, this, [this](QProcess::ProcessError) {
-    emit errorLineReceived(m_process.errorString());
-  });
-  connect(&m_process, qOverload<int, QProcess::ExitStatus>(&QProcess::finished), this,
-          [this](int exitCode, QProcess::ExitStatus) {
-            m_stdoutBuffer += m_process.readAllStandardOutput();
-            m_stderrBuffer += m_process.readAllStandardError();
-            flush(m_stdoutBuffer, false);
-            flush(m_stderrBuffer, true);
-            emit exited(exitCode);
-          });
-}
-
-ZuiProcess::~ZuiProcess() { stop(); }
-
-bool ZuiProcess::running() const { return m_process.state() != QProcess::NotRunning; }
-
-void ZuiProcess::start(const QString &executable, const QString &program,
-                       const QString &workingDirectory, const QString &loadPath) {
-  if (running() || executable.isEmpty() || program.isEmpty())
-    return;
-
-  QProcessEnvironment environment = QProcessEnvironment::systemEnvironment();
-  environment.insert(QStringLiteral("ZUI_PROJECT_DIR"), workingDirectory);
-  m_process.setProcessEnvironment(environment);
-  m_process.setWorkingDirectory(workingDirectory);
-  m_process.setProcessChannelMode(QProcess::SeparateChannels);
-
-  QStringList arguments;
-  if (!loadPath.isEmpty())
-    arguments << QStringLiteral("-I") << loadPath;
-  arguments << program;
-  m_process.start(executable, arguments, QIODevice::ReadWrite);
-}
-
-void ZuiProcess::write(const QString &data) {
-  if (!running())
-    return;
-  m_process.write(data.toUtf8());
-}
-
-void ZuiProcess::stop() {
-  if (!running())
-    return;
-  m_process.closeWriteChannel();
-  m_process.terminate();
-  if (!m_process.waitForFinished(1000)) {
-    m_process.kill();
-    m_process.waitForFinished(1000);
-  }
-}
-
-void ZuiProcess::consume(QByteArray &buffer, bool errorStream) {
-  qsizetype newline = -1;
-  while ((newline = buffer.indexOf('\n')) >= 0) {
-    const QString line = QString::fromUtf8(buffer.left(newline));
-    buffer.remove(0, newline + 1);
-    errorStream ? emit errorLineReceived(line) : emit lineReceived(line);
-  }
-}
-
-void ZuiProcess::flush(QByteArray &buffer, bool errorStream) {
-  consume(buffer, errorStream);
-  if (buffer.isEmpty())
-    return;
-  const QString line = QString::fromUtf8(buffer);
-  buffer.clear();
-  errorStream ? emit errorLineReceived(line) : emit lineReceived(line);
-}

data/native/ZuiProcess.h

@@ -1,34 +0,0 @@
-#pragma once
-
-#include <QObject>
-#include <QProcess>
-
-class ZuiProcess final : public QObject {
-  Q_OBJECT
-  Q_PROPERTY(bool running READ running NOTIFY runningChanged)
-
-public:
-  explicit ZuiProcess(QObject *parent = nullptr);
-  ~ZuiProcess() override;
-
-  bool running() const;
-
-  Q_INVOKABLE void start(const QString &executable, const QString &program,
-                         const QString &workingDirectory, const QString &loadPath);
-  Q_INVOKABLE void write(const QString &data);
-  Q_INVOKABLE void stop();
-
-signals:
-  void runningChanged();
-  void lineReceived(const QString &line);
-  void errorLineReceived(const QString &line);
-  void exited(int exitCode);
-
-private:
-  void consume(QByteArray &buffer, bool errorStream);
-  void flush(QByteArray &buffer, bool errorStream);
-
-  QProcess m_process;
-  QByteArray m_stdoutBuffer;
-  QByteArray m_stderrBuffer;
-};

data/native/main.cpp

@@ -1,64 +0,0 @@
-#include "ZuiClipboard.h"
-#include "ZuiProcess.h"
-
-#include <QCommandLineParser>
-#include <QDir>
-#include <QFileInfo>
-#include <QGuiApplication>
-#include <QQmlApplicationEngine>
-#include <QQmlContext>
-#include <QQuickStyle>
-
-#ifdef ZUI_HAS_WEBENGINE
-#include <QtWebEngineQuick/qtwebenginequickglobal.h>
-#endif
-
-int main(int argc, char *argv[]) {
-#ifdef ZUI_HAS_WEBENGINE
-  QtWebEngineQuick::initialize();
-#endif
-  QGuiApplication application(argc, argv);
-  QCoreApplication::setApplicationName(QStringLiteral("Zui"));
-  QCoreApplication::setOrganizationName(QStringLiteral("Zui"));
-  QQuickStyle::setStyle(QStringLiteral("Fusion"));
-
-  QCommandLineParser parser;
-  parser.setApplicationDescription(QStringLiteral("Zui cross-platform Qt host"));
-  parser.addHelpOption();
-  parser.addOption({QStringLiteral("qml-root"), QStringLiteral("Zui QML runtime directory"), QStringLiteral("path")});
-  parser.addOption({QStringLiteral("project"), QStringLiteral("Application project directory"), QStringLiteral("path")});
-  parser.addOption({QStringLiteral("program"), QStringLiteral("Ruby application entrypoint"), QStringLiteral("path")});
-  parser.addOption({QStringLiteral("ruby"), QStringLiteral("Ruby executable"), QStringLiteral("path"), QStringLiteral("ruby")});
-  parser.addOption({QStringLiteral("load-path"), QStringLiteral("Ruby framework load path"), QStringLiteral("path")});
-  parser.addOption({QStringLiteral("name"), QStringLiteral("Application name"), QStringLiteral("name"), QStringLiteral("Zui Application")});
-  parser.process(application);
-
-  const QString qmlRootValue = parser.value(QStringLiteral("qml-root"));
-  const QString projectValue = parser.value(QStringLiteral("project"));
-  const QString programValue = parser.value(QStringLiteral("program"));
-  const QString qmlRoot = QFileInfo(qmlRootValue).absoluteFilePath();
-  const QString project = QFileInfo(projectValue).absoluteFilePath();
-  const QString program = QFileInfo(programValue).absoluteFilePath();
-  const QFileInfo desktopFile(QDir(qmlRoot).filePath(QStringLiteral("Desktop.qml")));
-  if (qmlRootValue.isEmpty() || projectValue.isEmpty() || programValue.isEmpty()
-      || !desktopFile.isFile() || !QFileInfo(project).isDir() || !QFileInfo(program).isFile())
-    parser.showHelp(64);
-
-  ZuiProcess process;
-  ZuiClipboard clipboard;
-  QQmlApplicationEngine engine;
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiProcess"), &process);
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiClipboard"), &clipboard);
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiProjectDir"), project);
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiComponentDir"), QDir(qmlRoot).filePath(QStringLiteral("Components/Builtins")));
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiRubyExecutable"), parser.value(QStringLiteral("ruby")));
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiRubyProgram"), program);
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiRubyLoadPath"), parser.value(QStringLiteral("load-path")));
-  engine.rootContext()->setContextProperty(QStringLiteral("zuiApplicationName"), parser.value(QStringLiteral("name")));
-  engine.addImportPath(qmlRoot);
-
-  QObject::connect(&engine, &QQmlApplicationEngine::objectCreationFailed, &application,
-                   [] { QCoreApplication::exit(1); }, Qt::QueuedConnection);
-  engine.load(QUrl::fromLocalFile(QDir(qmlRoot).filePath(QStringLiteral("Desktop.qml"))));
-  return application.exec();
-}

data/vendor/host/linux-x86_64/PROVENANCE.md

@@ -1,15 +0,0 @@
-# Zui Linux host provenance
-
-- Target: Linux x86-64
-- Source: `native/` in this repository
-- Framework version: Zui 0.1.0
-- Compiler: GNU C++ 16.2.1
-- Qt: 6.11.2
-- Build type: CMake `Release`
-
-The binary is reproducible from the checked-in C++ sources with:
-
-```bash
-cmake -S native -B build -DCMAKE_BUILD_TYPE=Release
-cmake --build build --parallel
-```

data/vendor/host/linux-x86_64/zui-host.sha256

@@ -1 +0,0 @@
-de446bb598f922a7a58fe30127d88cae9602cf54bd819aa2b5c84447a51da7a4  zui-host