zui 0.0.1

data/lib/zui/distribution.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Zui
+  class Distribution
+    attr_reader :platform
+
+    def initialize(host: Host.new, platform: Platform.current, framework_root: FRAMEWORK_ROOT)
+      @host = host
+      @platform = platform.assert_supported!
+      @framework_root = framework_root
+    end
+
+    def bundle(source, name: nil, destination: nil)
+      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"))
+      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)
+
+      case platform.os
+      when :linux then bundle_linux(project, destination, app_name)
+      when :macos then bundle_macos(project, destination, app_name)
+      when :windows then bundle_windows(project, destination, app_name)
+      end
+      destination
+    rescue StandardError
+      FileUtils.remove_entry(destination) if 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"),
+                         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"))
+      write_linux_launcher(destination, app_name)
+      desktop_name = "#{slug(app_name)}.desktop"
+      File.write(File.join(destination, "share", "applications", desktop_name), <<~DESKTOP)
+        [Desktop Entry]
+        Type=Application
+        Name=#{app_name}
+        Exec=#{File.join(destination, "run")}
+        Terminal=false
+        Categories=Utility;
+      DESKTOP
+      write_manifest(destination, app_name)
+    end
+
+    def bundle_macos(project, destination, app_name)
+      contents = File.join(destination, "Contents")
+      macos = File.join(contents, "MacOS")
+      resources = File.join(contents, "Resources")
+      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"))
+      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))
+      write_manifest(resources, app_name)
+    end
+
+    def bundle_windows(project, destination, app_name)
+      FileUtils.mkdir_p([File.join(destination, "app"), File.join(destination, "bin"),
+                         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"))
+      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)
+    end
+
+    def install_application(source, destination)
+      entries = Dir.children(source).reject do |entry|
+        entry_path = File.join(source, entry)
+        %w[.git dist].include?(entry) || destination.start_with?("#{entry_path}#{File::SEPARATOR}")
+      end
+      FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, destination) unless entries.empty?
+    end
+
+    def install_runtime(destination)
+      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"))
+    end
+
+    def write_linux_launcher(destination, app_name)
+      File.write(File.join(destination, "run"), <<~SH)
+        #!/bin/sh
+        set -eu
+        bundle_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+        ruby_command=${ZUI_RUBY:-ruby}
+        exec "$bundle_dir/bin/zui-host" \
+          --qml-root "$bundle_dir/runtime/qml" \
+          --project "$bundle_dir/app" \
+          --program "$bundle_dir/app/main.rb" \
+          --ruby "$ruby_command" \
+          --load-path "$bundle_dir/runtime/lib" \
+          --name #{shell_quote(app_name)}
+      SH
+      FileUtils.chmod(0o755, File.join(destination, "run"))
+    end
+
+    def macos_launcher(app_name)
+      <<~SH
+        #!/bin/sh
+        set -eu
+        contents=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+        resources="$contents/Resources"
+        ruby_command=${ZUI_RUBY:-ruby}
+        exec "$contents/MacOS/zui-host" \
+          --qml-root "$resources/runtime/qml" \
+          --project "$resources/app" \
+          --program "$resources/app/main.rb" \
+          --ruby "$ruby_command" \
+          --load-path "$resources/runtime/lib" \
+          --name #{shell_quote(app_name)}
+      SH
+    end
+
+    def windows_ruby_launcher(app_name)
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "rbconfig"
+
+        bundle_dir = File.expand_path(__dir__)
+        arguments = [
+          File.join(bundle_dir, "bin", "zui-host.exe"),
+          "--qml-root", File.join(bundle_dir, "runtime", "qml"),
+          "--project", File.join(bundle_dir, "app"),
+          "--program", File.join(bundle_dir, "app", "main.rb"),
+          "--ruby", RbConfig.ruby,
+          "--load-path", File.join(bundle_dir, "runtime", "lib"),
+          "--name", #{app_name.to_s.dump}
+        ]
+        exec(*arguments)
+      RUBY
+    end
+
+    def windows_command_launcher
+      <<~CMD.gsub("\n", "\r\n")
+        @echo off
+        setlocal
+        if defined ZUI_RUBY (
+          "%ZUI_RUBY%" "%~dp0run.rb"
+        ) else (
+          ruby "%~dp0run.rb"
+        )
+        exit /b %ERRORLEVEL%
+      CMD
+    end
+
+    def info_plist(app_name)
+      identifier = "dev.zui.#{slug(app_name).tr("-", ".")}"
+      <<~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>CFBundleExecutable</key><string>run</string>
+          <key>CFBundleIdentifier</key><string>#{identifier}</string>
+          <key>CFBundleName</key><string>#{xml_escape(app_name)}</string>
+          <key>CFBundlePackageType</key><string>APPL</string>
+          <key>CFBundleShortVersionString</key><string>#{VERSION}</string>
+          <key>NSHighResolutionCapable</key><true/>
+        </dict></plist>
+      PLIST
+    end
+
+    def write_manifest(directory, app_name)
+      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
+      ))
+    end
+
+    def default_destination(project, app_name)
+      base = File.join(project, "dist")
+      platform.macos? ? File.join(base, "#{app_name}.app") : File.join(base, "#{slug(app_name)}-#{platform.id}")
+    end
+
+    def titleize(value) = value.split(/[-_]/).map(&:capitalize).join(" ")
+    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;")
+  end
+end

data/lib/zui/generator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Zui
+  class Generator
+    def initialize(path:, name: nil)
+      @path = File.expand_path(path)
+      @name = name || File.basename(@path).split(/[-_]/).map(&:capitalize).join(" ")
+    end
+
+    def create
+      raise ArgumentError, "destination already exists: #{@path}" if File.exist?(@path)
+      created = true
+      FileUtils.mkdir_p(File.join(@path, "components"))
+      File.write(File.join(@path, "main.rb"), main_program)
+      File.write(File.join(@path, "components", "welcome.rb"), welcome_component)
+      File.write(File.join(@path, "README.md"), readme)
+      @path
+    rescue StandardError
+      FileUtils.remove_entry(@path) if created && File.directory?(@path)
+      raise
+    end
+
+    private
+
+    def main_program
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "zui"
+        require_relative "components/welcome"
+
+        module #{constant_name}
+          def self.build
+            Zui::Application.new(ui: WelcomeComponent) do
+              app :main, title: "#{@name}", width: 760, height: 520 do
+                welcome_card(title: "Welcome to #{@name}", message: "A native cross-platform Zui application.")
+              end
+            end
+          end
+
+          def self.run = build.run
+        end
+
+        #{constant_name}.run
+      RUBY
+    end
+
+    def welcome_component
+      <<~RUBY
+        # frozen_string_literal: true
+
+        module WelcomeComponent
+          def welcome_card(title:, message:)
+            card padding: 24, spacing: 12 do
+              text title, style: :heading
+              text message, wrap: true
+            end
+          end
+        end
+      RUBY
+    end
+
+    def readme
+      <<~MARKDOWN
+        # #{@name}
+
+        A native Linux, macOS, and Windows desktop application written in Ruby with Zui.
+
+        ```bash
+        zui run main.rb
+        zui bundle
+        ```
+      MARKDOWN
+    end
+
+    def constant_name
+      value = @name.scan(/[a-z0-9]+/i).map { |part| part[0].upcase + part[1..].to_s }.join
+      value = "Application#{value}" if value.match?(/\A\d/)
+      value.empty? ? "ZuiApplication" : value
+    end
+  end
+end

data/lib/zui/host.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Zui
+  class Host
+    attr_reader :platform
+
+    def initialize(platform: Platform.current, framework_root: FRAMEWORK_ROOT, environment: ENV)
+      @platform = platform.assert_supported!
+      @framework_root = framework_root
+      @environment = environment
+    end
+
+    def executable(build: true)
+      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
+
+      build!(cached)
+    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 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
+    end
+
+    private
+
+    def bundled
+      File.join(@framework_root, "vendor", "host", platform.id, executable_name)
+    end
+
+    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 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
+    end
+
+    def executable_name = platform.os == :windows ? "zui-host.exe" : "zui-host"
+
+    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/node.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Zui
+  class Node
+    attr_reader :type, :id, :props, :children, :events
+
+    def initialize(type:, id:, props: {})
+      @type = type.to_s
+      @id = id.to_s
+      @props = props.transform_keys(&:to_s)
+      @children = []
+      @events = []
+    end
+
+    def to_h
+      result = { "type" => type, "id" => id }
+      result["props"] = props unless props.empty?
+      result["children"] = children.map(&:to_h) unless children.empty?
+      result["events"] = events unless events.empty?
+      result
+    end
+
+    def subscribe(event)
+      @events << event.to_s unless @events.include?(event.to_s)
+    end
+  end
+
+  Binding = Struct.new(:node, :property, :reader, :last_value, :animation, keyword_init: true)
+  StructuralBinding = Struct.new(:node, :renderer, :last_children, keyword_init: true)
+end

data/lib/zui/platform.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Zui
+  Platform = Struct.new(:os, :arch, keyword_init: true) do
+    SUPPORTED_OSES = %i[linux macos windows].freeze
+
+    def self.current
+      detect(RbConfig::CONFIG.fetch("host_os"), RbConfig::CONFIG.fetch("host_cpu"))
+    end
+
+    def self.detect(host_os, host_cpu)
+      os = case host_os.to_s
+           when /darwin|mac\s?os/i then :macos
+           when /linux/i then :linux
+           when /mswin|mingw|cygwin|windows/i then :windows
+           else :unsupported
+           end
+      arch = case host_cpu.to_s
+             when /aarch64|arm64/i then :arm64
+             when /x86_64|amd64|x64/i then :x86_64
+             else host_cpu.to_s.downcase.gsub(/[^a-z0-9_]+/, "_").to_sym
+             end
+      new(os:, arch:)
+    end
+
+    def supported? = SUPPORTED_OSES.include?(os)
+    def id = "#{os}-#{arch}"
+    def linux? = os == :linux
+    def macos? = os == :macos
+    def windows? = os == :windows
+
+    def assert_supported!
+      return self if supported?
+
+      raise ArgumentError, "Zui desktop applications support Linux, macOS, and Windows; detected #{os}/#{arch}"
+    end
+  end
+end

data/lib/zui/protocol.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Zui
+  PROTOCOL_VERSION = 1
+  MAX_MESSAGE_BYTES = 1_048_576
+  class AsciiPattern
+    def initialize(min:, max:, first: nil, rest:)
+      @min = min
+      @max = max
+      @first = first
+      @rest = rest
+    end
+
+    def match?(value)
+      text = value.to_s
+      return false if text.length < @min || text.length > @max
+      return false if @first && !@first.include?(text[0])
+      text.each_char.all? { |character| @rest.include?(character) }
+    end
+  end
+
+  LOWER = ("a".."z").to_a.join.freeze
+  UPPER = ("A".."Z").to_a.join.freeze
+  DIGITS = ("0".."9").to_a.join.freeze
+  VALID_ID = AsciiPattern.new(min: 1, max: 128, rest: LOWER + UPPER + DIGITS + "_.:-")
+  VALID_EVENT = AsciiPattern.new(min: 1, max: 64, first: LOWER, rest: LOWER + DIGITS + "_")
+
+  class ProtocolError < StandardError; end
+end

data/lib/zui/runner.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Zui
+  class Runner
+    def initialize(host: Host.new, framework_root: FRAMEWORK_ROOT, ruby: RbConfig.ruby)
+      @host = host
+      @framework_root = framework_root
+      @ruby = ruby
+    end
+
+    def run(file, name: nil, environment: ENV.to_h)
+      program = File.expand_path(file)
+      raise ArgumentError, "Ruby file not found: #{program}" unless File.file?(program)
+      executable = @host.executable
+      project = File.dirname(program)
+      arguments = [
+        executable,
+        "--qml-root", @framework_root,
+        "--project", project,
+        "--program", program,
+        "--ruby", @ruby,
+        "--load-path", File.join(@framework_root, "lib"),
+        "--name", name || project_name(project)
+      ]
+      system(environment, *arguments)
+      $?&.exitstatus || 1
+    end
+
+    private
+
+    def project_name(path)
+      File.basename(path).split(/[-_]/).map(&:capitalize).join(" ")
+    end
+  end
+end

data/lib/zui/runtime.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Zui
+  module Runtime
+    module_function
+
+    QML_FILES = %w[Desktop.qml Service.qml ControlNode.qml].freeze
+    QML_DIRECTORIES = %w[Components Controls Theme].freeze
+
+    def install_qml(destination, framework_root: FRAMEWORK_ROOT)
+      FileUtils.mkdir_p(destination)
+      QML_FILES.each do |name|
+        FileUtils.cp(File.join(framework_root, name), File.join(destination, name))
+      end
+      QML_DIRECTORIES.each do |name|
+        FileUtils.cp_r(File.join(framework_root, name), File.join(destination, name))
+      end
+      destination
+    end
+  end
+end