zui 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42bdb62a57c863cdc40283e45b894097dc811f23f3d8d081ae05bc1e6619aece
-  data.tar.gz: 7da4bafa4b0efa12cc5c2b89f88210044154dec373e5f0b419f900dae471727d
+  metadata.gz: 708ca03d2896630151177ee0b6fe2d38a5a6e8da0ec03899a89342a881f431da
+  data.tar.gz: c2342386d280806246ce4e2dc6ef296b3e65474ff352bbca8e5085313c534886
 SHA512:
-  metadata.gz: 5f8016e274b0cec1f2a8614327e7c7ab95762a836a7d55fe2a1e716d231fe6ef2c12a56f28de3df09b907471a6fe2156a42d25a897a80ab483f66337c3a47ad9
-  data.tar.gz: 033e22d2907f8c0fa66badd46eaec2f1636e1388c272c16210b0ede3dad7a561fc185b7372b2952ee14273c97e36ccbbe85b364b664481448175e438d13f1956
+  metadata.gz: 8529e5aa1ea6f062b56dec92e568895781f14ad8c5e0f7e22032d763f9f4c3f086c272203843de62bb613b8aedc5b28ac4b32bd9ceffbe4f3ec98e611e462375
+  data.tar.gz: e8e6047c3ec7423a2b49a0cb70a83acdd5e8315d974ebe7203e3e92492a864f0d13717a504e2bed599a036dcb902bdc0fdeac490a445c098c4e4d7a8f9cf1bed

data/README.md

@@ -188,7 +188,7 @@ uses a system Qt installation, or downloads an asset for a different platform. S
 
 ## Component catalog
 
-Zui 0.0.9 registers **241 built-in components**. Every entry has a named Ruby builder method,
+Zui 0.0.10 registers **241 built-in components**. Every entry has a named Ruby builder method,
 property and event schema, native QML renderer, reactive patch support, and contract tests.
 
 | Category | Count | Representative components |
@@ -217,6 +217,8 @@ an explicit error.
 
 | Command | Purpose |
 | --- | --- |
+| `zui --help` | List every command and global option |
+| `zui help COMMAND` | Show detailed usage, options, and examples for one command |
 | `zui new NAME` | Generate a pure-Ruby application, `Gemfile`, distribution config, and reusable UI module |
 | `zui doctor` | Report Ruby, platform, native-client, run, and bundle readiness without changing anything |
 | `zui doctor --fix` | Download, verify, and install the missing native client and lite mruby runtime |
@@ -229,6 +231,9 @@ an explicit error.
 | `zui bundle --dist [DIRECTORY]` | Build release installers from the required project-root `config.rb` |
 | `zui version` | Print the installed framework version |
 
+Every command also supports `-h` and `--help` directly, such as `zui bundle --help`.
+Usage errors point to the relevant command help without starting downloads, builds, or applications.
+
 Zui has no separate validation command. Ruby, DSL, schema, resource, protocol, and renderer errors
 are reported by the operation that encounters them.
 

data/lib/zui/cli.rb

@@ -1,11 +1,127 @@
 # frozen_string_literal: true
 
 require "json"
+require "optparse"
 require "rbconfig"
 
 module Zui
   class CLI
-    USAGE = "Usage: zui <new NAME|configure|doctor [--fix]|run FILE|bundle [--dist] [--lite|--full] [--no-tree-shake] [DIRECTORY]|version>"
+    class UsageError < ArgumentError; end
+
+    COMMANDS = {
+      "new" => "Create a new Zui application",
+      "configure" => "Install the native client and lite runtime",
+      "doctor" => "Check or repair the local Zui installation",
+      "run" => "Run a Ruby application with the native client",
+      "bundle" => "Build a standalone app or release installer",
+      "version" => "Print the installed Zui version"
+    }.freeze
+
+    GENERAL_HELP = <<~HELP.freeze
+      Zui #{VERSION} — native desktop applications in Ruby
+
+      Usage:
+        zui COMMAND [arguments] [options]
+
+      Commands:
+        new NAME       #{COMMANDS.fetch("new")}
+        configure      #{COMMANDS.fetch("configure")}
+        doctor         #{COMMANDS.fetch("doctor")}
+        run FILE       #{COMMANDS.fetch("run")}
+        bundle [DIR]   #{COMMANDS.fetch("bundle")}
+        version        #{COMMANDS.fetch("version")}
+
+      Global options:
+        -h, --help     Show this help
+        -v, --version  Print the installed Zui version
+
+      Run `zui help COMMAND` or `zui COMMAND --help` for command details.
+    HELP
+
+    COMMAND_HELP = {
+      "new" => <<~HELP,
+        Create a new Zui application.
+
+        Usage:
+          zui new NAME
+
+        NAME becomes both the project directory and display name. Underscores,
+        hyphens, and spaces are normalized; `smart_home` becomes “Smart Home”.
+        The project includes Ruby sources, distribution config, and release icons.
+
+        Example:
+          zui new smart_home
+      HELP
+      "configure" => <<~HELP,
+        Install the verified native client and lite mruby runtime.
+
+        Usage:
+          zui configure
+
+        Downloads the platform assets for this Zui version from GitHub Releases,
+        verifies their checksums and manifests, and installs them in the user cache.
+
+        Equivalent repair command:
+          zui doctor --fix
+      HELP
+      "doctor" => <<~HELP,
+        Check or repair the local Zui installation.
+
+        Usage:
+          zui doctor [options]
+
+        Options:
+          -f, --fix  Download, verify, and install missing platform assets
+
+        Without --fix, doctor is read-only and exits nonzero when setup is incomplete.
+
+        Examples:
+          zui doctor
+          zui doctor --fix
+      HELP
+      "run" => <<~HELP,
+        Run a Ruby application with the private native client.
+
+        Usage:
+          zui run FILE
+
+        FILE is the Ruby entry point for the application.
+
+        Example:
+          zui run main.rb
+      HELP
+      "bundle" => <<~HELP,
+        Build a standalone application or platform release installer.
+
+        Usage:
+          zui bundle [DIRECTORY] [options]
+
+        Options:
+          -n, --name NAME       Override the app name for a non-distribution bundle
+          -o, --output PATH     Set the bundle destination or distribution directory
+              --lite            Embed the portable mruby runtime (default)
+              --full            Embed private CRuby and the project's locked gems
+              --dist            Build platform installers using config.rb
+              --no-tree-shake   Keep the complete component and Qt feature catalog
+
+        DIRECTORY defaults to the current directory. --lite and --full are mutually
+        exclusive. --dist reads the app name and release metadata from config.rb.
+
+        Examples:
+          zui bundle
+          zui bundle --full .
+          zui bundle --name "Smart Home" --output dist/SmartHome.app
+          zui bundle --dist --full .
+      HELP
+      "version" => <<~HELP
+        Print the installed Zui version.
+
+        Usage:
+          zui version
+          zui --version
+          zui -v
+      HELP
+    }.freeze
 
     def self.run(arguments, out: $stdout, err: $stderr)
       new(out:, err:).run(arguments.dup)
@@ -18,19 +134,26 @@ module Zui
 
     def run(arguments)
       command = arguments.shift
+      @active_command = command
+      return show_general_help if command.nil? || %w[-h --help].include?(command)
+      return show_command_help(arguments) if command == "help"
+      return show_named_help(command) if COMMANDS.key?(command) && help_requested?(arguments)
+
       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)
-      when "version", "--version", "-v" then @out.puts(VERSION); 0
-      else
-        @err.puts(USAGE)
-        command.nil? ? 0 : 64
+      when "version", "--version", "-v" then print_version(arguments)
+      else unknown_command(command)
       end
     rescue Interrupt
       130
+    rescue OptionParser::ParseError, UsageError => error
+      @err.puts("zui: #{error.message}")
+      @err.puts(help_hint)
+      1
     rescue ArgumentError, SystemCallError, JSON::ParserError => error
       @err.puts("zui: #{error.message}")
       1
@@ -39,8 +162,10 @@ module Zui
     private
 
     def new_project(arguments)
-      name = arguments.shift || raise(ArgumentError, "new requires a project name")
-      raise ArgumentError, "new accepts only a project name" unless arguments.empty?
+      parse_no_options!(arguments)
+      name = arguments.shift || raise(UsageError, "new requires a project name")
+      raise UsageError, "new accepts only one project name" unless arguments.empty?
+
       destination = File.expand_path(slug(name))
       Generator.new(path: destination, name:).create
       @out.puts("Created Zui application in #{destination}")
@@ -48,35 +173,46 @@ module Zui
     end
 
     def run_file(arguments)
-      file = File.expand_path(arguments.shift || raise(ArgumentError, "run requires a Ruby file"))
-      raise ArgumentError, "run accepts one Ruby file" unless arguments.empty?
+      parse_no_options!(arguments)
+      file = File.expand_path(arguments.shift || raise(UsageError, "run requires a Ruby file"))
+      raise UsageError, "run accepts only one Ruby file" unless arguments.empty?
+
       Runner.new.run(file)
     end
 
     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
+      options = { tree_shake: true }
+      parser = OptionParser.new do |option|
+        option.on("-n NAME", "--name NAME") { |value| options[:name] = value }
+        option.on("-o PATH", "--output PATH") { |value| options[:destination] = value }
+        option.on("--lite") { options[:lite] = true }
+        option.on("--full") { options[:full] = true }
+        option.on("--dist") { options[:create_installers] = true }
+        option.on("--no-tree-shake") { options[:tree_shake] = false }
+      end
+      parser.parse!(arguments)
+      if options[:lite] && options[:full]
+        raise UsageError, "bundle accepts only one of --lite or --full"
+      end
+
+      runtime_mode = options[:full] ? :full : :lite
       source = File.expand_path(arguments.shift || Dir.pwd)
-      raise ArgumentError, "bundle accepts one directory" unless arguments.empty?
+      raise UsageError, "bundle accepts only one directory" unless arguments.empty?
 
-      if create_installers
-        raise ArgumentError, "--name cannot be used with --dist; set name in config.rb" if name
+      if options[:create_installers]
+        if options[:name]
+          raise UsageError, "--name cannot be used with --dist; set name in config.rb"
+        end
 
-        packager = DistPackager.new(tree_shake:, runtime_mode:)
-        paths = packager.package(source, output: destination)
+        packager = DistPackager.new(tree_shake: options[:tree_shake], runtime_mode:)
+        paths = packager.package(source, output: options[: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:)
+      distribution = Distribution.new(tree_shake: options[:tree_shake], runtime_mode:)
+      path = distribution.bundle(source, name: options[:name], destination: options[:destination])
       @out.puts("Bundled #{Platform.current.os} application in #{path}")
       report_tree_shaking(distribution.tree_shake_report)
       0
@@ -89,8 +225,10 @@ module Zui
     end
 
     def doctor(arguments)
-      fix = arguments.delete("--fix")
-      raise ArgumentError, "doctor accepts only --fix" unless arguments.empty?
+      fix = false
+      OptionParser.new { |option| option.on("-f", "--fix") { fix = true } }.parse!(arguments)
+      raise UsageError, "doctor accepts no positional arguments" unless arguments.empty?
+
       platform = Platform.current
       @out.puts("Zui #{VERSION}")
       @out.puts("Platform: #{platform.id}#{platform.supported? ? '' : ' (unsupported)'}")
@@ -124,7 +262,9 @@ module Zui
     end
 
     def configure(arguments)
-      raise ArgumentError, "configure accepts no arguments" unless arguments.empty?
+      parse_no_options!(arguments)
+      raise UsageError, "configure accepts no arguments" unless arguments.empty?
+
       platform = Platform.current.assert_supported!
       client = Client.new(platform:)
       lite_runtime = LiteRuntime.new(platform:)
@@ -143,17 +283,60 @@ module Zui
       @out.puts("Bundle --full: ready (uses this Ruby and the project's locked gems)")
     end
 
-    def option_value(arguments, name)
-      index = arguments.index(name)
-      return nil unless index
-      raise ArgumentError, "#{name} requires a value" if index == arguments.length - 1
-      arguments.delete_at(index)
-      arguments.delete_at(index)
+    def show_general_help
+      @out.puts(GENERAL_HELP)
+      0
+    end
+
+    def show_command_help(arguments)
+      return show_general_help if arguments.empty? || arguments == ["-h"] || arguments == ["--help"]
+      raise UsageError, "help accepts only one command" unless arguments.length == 1
+
+      show_named_help(arguments.first)
+    end
+
+    def show_named_help(command)
+      help = COMMAND_HELP[command]
+      return unknown_command(command) unless help
+
+      @out.puts(help)
+      0
+    end
+
+    def help_requested?(arguments)
+      arguments.any? { |argument| %w[-h --help].include?(argument) }
+    end
+
+    def print_version(arguments)
+      parse_no_options!(arguments)
+      raise UsageError, "version accepts no arguments" unless arguments.empty?
+
+      @out.puts(VERSION)
+      0
+    end
+
+    def unknown_command(command)
+      @err.puts("zui: unknown command #{command.inspect}")
+      @err.puts("Run `zui --help` to see available commands.")
+      64
+    end
+
+    def help_hint
+      if COMMANDS.key?(@active_command)
+        "Run `zui help #{@active_command}` for usage."
+      else
+        "Run `zui --help` to see available commands."
+      end
+    end
+
+    def parse_no_options!(arguments)
+      OptionParser.new.parse!(arguments)
     end
 
     def slug(value)
-      result = value.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
-      raise ArgumentError, "name must contain letters or numbers" if result.empty?
+      result = value.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\z/, "")
+      raise UsageError, "name must contain letters or numbers" if result.empty?
+
       result
     end
 

data/lib/zui.rb

@@ -28,7 +28,7 @@ require_relative "zui/distribution"
 require_relative "zui/dist_packager"
 
 module Zui
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
   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.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Adam Moussa Ali