kdeploy 1.2.33 → 1.2.39

data/README_EN.md

@@ -97,6 +97,12 @@ kdeploy version
 
 You should see the version information and banner.
 
+**If `kdeploy` is not found**: the gem executable directory may not be in your PATH. Add to `~/.zshrc` or `~/.bashrc` then run `source ~/.zshrc`:
+
+```bash
+export PATH="$(ruby -e 'puts Gem.bindir'):$PATH"
+```
+
 ### Shell Completion
 
 Kdeploy automatically configures shell completion during installation. If needed, manually add to your shell config:
@@ -136,35 +142,30 @@ This creates a new directory with:
 
 ### 2. Configure Hosts and Tasks
 
-Edit `deploy.rb`:
+Edit `deploy.rb` (using Chef-style resource DSL):
 
 ```ruby
 # Define hosts
 host "web01", user: "ubuntu", ip: "10.0.0.1", key: "~/.ssh/id_rsa"
 host "web02", user: "ubuntu", ip: "10.0.0.2", key: "~/.ssh/id_rsa"
-
-# Define roles
 role :web, %w[web01 web02]
 
 # Define deployment task
-task :deploy, roles: :web do
-  run <<~SHELL
-    sudo systemctl stop nginx
-    echo "Deploying application..."
-  SHELL
-
-  upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-    domain_name: "example.com",
-    port: 3000
-
-  run "sudo systemctl start nginx"
+task :deploy_web, roles: :web do
+  package "nginx"
+  directory "/etc/nginx/conf.d"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+    variables: { domain_name: "example.com", port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true
+  service "nginx", action: %i[enable restart]
 end
 ```
 
 ### 3. Run Deployment
 
 ```bash
-kdeploy execute deploy.rb deploy
+kdeploy execute deploy.rb deploy_web
 ```
 
 ## 📖 Usage Guide
@@ -355,7 +356,7 @@ end
 
 ```ruby
 task :deploy_web, roles: :web do
-  run "sudo systemctl restart nginx"
+  service "nginx", action: :restart
 end
 ```
 
@@ -363,29 +364,22 @@ end
 
 ```ruby
 task :maintenance, on: %w[web01] do
-  run <<~SHELL
-    sudo systemctl stop nginx
-    sudo apt-get update && sudo apt-get upgrade -y
-    sudo systemctl start nginx
-  SHELL
+  service "nginx", action: :stop
+  run "apt-get update && apt-get upgrade -y", sudo: true
+  service "nginx", action: %i[start enable]
 end
 ```
 
 #### Task with Multiple Commands
 
 ```ruby
-task :deploy, roles: :web do
-  # Stop service
-  run "sudo systemctl stop nginx"
-
-  # Upload configuration
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-
-  # Start service
-  run "sudo systemctl start nginx"
-
-  # Verify status
-  run "sudo systemctl status nginx"
+task :deploy_web, roles: :web do
+  package "nginx"
+  directory "/etc/nginx/conf.d"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true
+  service "nginx", action: %i[enable restart]
 end
 ```
 
@@ -486,6 +480,67 @@ upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
 - `destination`: Remote file path
 - `variables`: Hash of variables for template rendering
 
+### Chef-Style Resource DSL
+
+Kdeploy provides a declarative resource DSL similar to Chef, which can replace or mix with low-level primitives (`run`, `upload`, `upload_template`).
+
+#### `package` - Install System Packages
+
+```ruby
+package "nginx"
+package "nginx", version: "1.18"
+package "nginx", platform: :yum  # CentOS/RHEL
+```
+
+Uses apt (Ubuntu/Debian) by default; `platform: :yum` generates yum commands.
+
+#### `service` - Manage System Services (systemd)
+
+```ruby
+service "nginx", action: [:enable, :start]
+service "nginx", action: :restart
+service "nginx", action: [:stop, :disable]
+```
+
+Supports `:start`, `:stop`, `:restart`, `:reload`, `:enable`, `:disable`.
+
+#### `template` - Deploy ERB Templates
+
+```ruby
+template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+# Or block syntax
+template "/etc/app.conf" do
+  source "./config/app.erb"
+  variables(domain: "example.com")
+end
+```
+
+#### `file` - Upload Local Files
+
+```ruby
+file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+```
+
+#### `directory` - Ensure Remote Directory Exists
+
+```ruby
+directory "/etc/nginx/conf.d"
+directory "/var/log/app", mode: "0755"
+```
+
+**Example: Deploy Nginx Using Resource DSL**
+
+```ruby
+task :deploy_nginx, roles: :web do
+  package "nginx"
+  directory "/etc/nginx/conf.d"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true
+  service "nginx", action: %i[enable restart]
+end
+```
+
 ### Template Support
 
 Kdeploy supports ERB (Embedded Ruby) templates for dynamic configuration generation.
@@ -532,11 +587,8 @@ http {
 
 ```ruby
 task :deploy_config do
-  upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-    domain_name: "example.com",
-    port: 3000,
-    worker_processes: 4,
-    worker_connections: 2048
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+    variables: { domain_name: "example.com", port: 3000, worker_processes: 4, worker_connections: 2048 }
 end
 ```
 
@@ -597,15 +649,11 @@ Use Ruby conditionals in your deployment files:
 
 ```ruby
 task :deploy do
-  if ENV['ENVIRONMENT'] == 'production'
-    run "sudo systemctl stop nginx"
-  end
+  service "nginx", action: :stop if ENV['ENVIRONMENT'] == 'production'
 
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+  file "/etc/nginx/nginx.conf", source: "./config/nginx.conf"
 
-  if ENV['ENVIRONMENT'] == 'production'
-    run "sudo systemctl start nginx"
-  end
+  service "nginx", action: :start if ENV['ENVIRONMENT'] == 'production'
 end
 ```
 
@@ -628,9 +676,10 @@ end
 
 ```ruby
 task :deploy do
-  run "sudo systemctl stop nginx" || raise "Failed to stop nginx"
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-  run "sudo systemctl start nginx" || raise "Failed to start nginx"
+  service "nginx", action: :stop
+  file "/etc/nginx/nginx.conf", source: "./config/nginx.conf"
+  run "nginx -t", sudo: true  # run raises on invalid config
+  service "nginx", action: :start
 end
 ```
 
@@ -746,10 +795,9 @@ end
 ### 3. Use Templates for Dynamic Configuration
 
 ```ruby
-# ✅ Good - Use templates
-upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-  domain_name: "example.com",
-  port: 3000
+# ✅ Good - Use template resource
+template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+  variables: { domain_name: "example.com", port: 3000 }
 
 # ❌ Avoid - Hardcoding values
 run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
@@ -759,12 +807,10 @@ run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
 
 ```ruby
 task :deploy do
-  # Validate configuration
-  run "nginx -t" || raise "Nginx configuration is invalid"
-
-  # Deploy
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-  run "sudo systemctl reload nginx"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true  # run raises on invalid config
+  service "nginx", action: :reload
 end
 ```
 
@@ -883,7 +929,6 @@ Enable verbose output by checking the execution output. Kdeploy provides detaile
 - **Executor** (`executor.rb`): SSH/SCP execution engine
 - **Runner** (`runner.rb`): Concurrent task execution coordinator
 - **CommandExecutor** (`command_executor.rb`): Individual command execution
-- **CommandGrouper** (`command_grouper.rb`): Command grouping logic
 - **Template** (`template.rb`): ERB template rendering
 - **Output** (`output.rb`): Output formatting and display
 - **Configuration** (`configuration.rb`): Configuration management
@@ -893,10 +938,9 @@ Enable verbose output by checking the execution output. Kdeploy provides detaile
 
 1. **Parse Configuration**: Load and parse `deploy.rb`
 2. **Resolve Hosts**: Determine target hosts based on task definition
-3. **Group Commands**: Group commands by type for efficient execution
-4. **Execute Concurrently**: Run tasks in parallel across hosts
-5. **Collect Results**: Gather execution results and status
-6. **Display Output**: Format and display results to user
+3. **Execute Concurrently**: Run tasks in parallel across hosts, executing commands in order per host
+4. **Collect Results**: Gather execution results and status
+5. **Display Output**: Format and display results to user
 
 ### Concurrency Model
 
@@ -936,7 +980,6 @@ kdeploy/
 │       ├── executor.rb         # SSH/SCP executor
 │       ├── runner.rb           # Task runner
 │       ├── command_executor.rb # Command executor
-│       ├── command_grouper.rb  # Command grouper
 │       ├── template.rb         # Template handler
 │       ├── output.rb           # Output interface
 │       ├── configuration.rb    # Configuration
@@ -1018,9 +1061,16 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 
 ## 📚 Examples
 
-### Example Projects
+### Example Project
 
-Check out the [example project](https://github.com/kevin197011/kdeploy-app) for a complete deployment setup.
+The [sample/](sample/) directory in this repo provides a complete example with Nginx, Node Exporter, directory sync tasks, and Vagrant support for local testing:
+
+```bash
+cd sample
+vagrant up
+kdeploy execute deploy.rb deploy_web --dry-run  # Preview
+kdeploy execute deploy.rb deploy_web            # Execute
+```
 
 ### Common Deployment Scenarios
 
@@ -1061,12 +1111,21 @@ end
 
 ```ruby
 task :update_config, roles: :web do
-  upload_template "./config/app.yml.erb", "/etc/app/config.yml",
-    environment: "production",
-    database_url: ENV['DATABASE_URL'],
-    redis_url: ENV['REDIS_URL']
+  template "/etc/app/config.yml", source: "./config/app.yml.erb",
+    variables: { environment: "production", database_url: ENV['DATABASE_URL'], redis_url: ENV['REDIS_URL'] }
+  service "app", action: :reload
+end
+```
 
-  run "sudo systemctl reload app"
+#### Directory Sync Deployment
+
+```ruby
+task :deploy_app, roles: :web do
+  sync "./app", "/var/www/app",
+    ignore: [".git", "*.log", "node_modules", ".env.local", "*.tmp"],
+    delete: true
+  sync "./config", "/etc/app", exclude: ["*.example", "*.bak"]
+  service "app", action: :restart
 end
 ```
 
@@ -1079,7 +1138,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 - **GitHub**: https://github.com/kevin197011/kdeploy
 - **RubyGems**: https://rubygems.org/gems/kdeploy
 - **Issues**: https://github.com/kevin197011/kdeploy/issues
-- **Example Project**: https://github.com/kevin197011/kdeploy-app
+- **Sample**: [sample/](sample/) directory (includes Vagrant config)
 
 ## 🙏 Acknowledgments
 

data/lib/kdeploy/cli.rb

@@ -142,21 +142,24 @@ module Kdeploy
       print_summary(results, formatter) if show_summary
     end
 
-    def print_host_result(_host, result, formatter)
+    def print_host_result(host, result, formatter)
       if %i[success changed].include?(result[:status])
-        print_success_result(result, formatter)
+        print_success_result(host, result, formatter)
       else
-        print_failure_result(result, formatter)
+        print_failure_result(host, result, formatter)
       end
+
+      duration = formatter.calculate_host_duration(result)
+      puts "#{formatter.host_prefix(host)}#{formatter.format_host_completed(duration)}" if duration.positive?
     end
 
-    def print_success_result(result, formatter)
+    def print_success_result(host, result, formatter)
       shown = {}
       grouped = group_output_by_type(result[:output])
 
       grouped.each do |type, steps|
         output_lines = format_steps_by_type(type, steps, shown, formatter)
-        output_lines.each { |line| puts line }
+        output_lines.each { |line| puts "#{formatter.host_prefix(host)}#{line}" }
       end
     end
 
@@ -179,9 +182,21 @@ module Kdeploy
       end
     end
 
-    def print_failure_result(result, formatter)
+    def print_failure_result(host, result, formatter)
       error_message = extract_error_message(result)
-      puts formatter.format_error(error_message)
+      puts "#{formatter.host_prefix(host)}#{formatter.format_error(error_message)}"
+
+      # On failure, show steps that were executed (and any captured output)
+      # to make troubleshooting easier, even if --debug is not enabled.
+      return unless result[:output].is_a?(Array) && result[:output].any?
+
+      debug_formatter = OutputFormatter.new(debug: true)
+      shown = {}
+      grouped = group_output_by_type(result[:output])
+      grouped.each do |type, steps|
+        output_lines = format_steps_by_type(type, steps, shown, debug_formatter)
+        output_lines.each { |line| puts "#{debug_formatter.host_prefix(host)}#{line}" }
+      end
     end
 
     def print_summary(results, formatter)
@@ -214,6 +229,9 @@ module Kdeploy
         task_results = execute_single_task(task)
         # Collect results for final summary
         all_results[task] = task_results if task_results
+
+        # Stop executing remaining tasks once any host failed for this task.
+        break if task_failed?(task_results)
       end
 
       # Show combined summary at the end for all tasks
@@ -275,6 +293,12 @@ module Kdeploy
       end
     end
 
+    def task_failed?(task_results)
+      return false unless task_results.is_a?(Hash)
+
+      task_results.values.any? { |result| result[:status] == :failed }
+    end
+
     def print_all_tasks_summary(all_results)
       debug_mode = options[:debug] || false
       formatter = OutputFormatter.new(debug: debug_mode)

data/lib/kdeploy/command_executor.rb

@@ -11,26 +11,18 @@ module Kdeploy
       @retry_delay = retry_delay.to_f
     end
 
-    def execute_run(command, host_name)
+    def execute_run(command, _host_name)
       cmd = command[:command]
       use_sudo = command[:sudo]
-      show_command_header(host_name, :run, cmd)
-
-      # Show progress indicator for long-running commands
-      pastel = @output.respond_to?(:pastel) ? @output.pastel : Pastel.new
 
       result, duration = measure_time do
         with_retries { @executor.execute(cmd, use_sudo: use_sudo) }
       end
 
-      # Show execution time if command took more than 1 second
-      @output.write_line(pastel.dim("    [completed in #{format('%.2f', duration)}s]")) if duration > 1.0
-
       { command: cmd, output: result, duration: duration, type: :run }
     end
 
-    def execute_upload(command, host_name)
-      show_command_header(host_name, :upload, "#{command[:source]} -> #{command[:destination]}")
+    def execute_upload(command, _host_name)
       _result, duration = measure_time do
         with_retries { @executor.upload(command[:source], command[:destination]) }
       end
@@ -41,8 +33,7 @@ module Kdeploy
       }
     end
 
-    def execute_upload_template(command, host_name)
-      show_command_header(host_name, :upload_template, "#{command[:source]} -> #{command[:destination]}")
+    def execute_upload_template(command, _host_name)
       _result, duration = measure_time do
         with_retries do
           @executor.upload_template(command[:source], command[:destination], command[:variables])
@@ -55,11 +46,9 @@ module Kdeploy
       }
     end
 
-    def execute_sync(command, host_name)
+    def execute_sync(command, _host_name)
       source = command[:source]
       destination = command[:destination]
-      description = build_sync_description(source, destination, command[:delete])
-      show_command_header(host_name, :sync, description)
 
       result, duration = measure_time do
         with_retries do
@@ -78,12 +67,6 @@ module Kdeploy
 
     private
 
-    def build_sync_description(source, destination, delete)
-      desc = "sync: #{source} -> #{destination}"
-      desc += " (delete: #{delete})" if delete
-      desc
-    end
-
     def build_sync_result(source, destination, result, duration)
       {
         command: "sync: #{source} -> #{destination}",
@@ -115,32 +98,5 @@ module Kdeploy
         retry
       end
     end
-
-    def show_command_header(host_name, type, description)
-      # Don't show command header during execution - it will be shown in results
-      # This reduces noise during execution
-    end
-
-    def pastel_instance
-      @output.respond_to?(:pastel) ? @output.pastel : Pastel.new
-    end
-
-    def format_command_by_type(type, description, pastel)
-      case type
-      when :run
-        format_run_command(description, pastel)
-      when :upload
-        @output.write_line(pastel.green("  [upload] #{description}"))
-      when :upload_template
-        @output.write_line(pastel.yellow("  [template] #{description}"))
-      end
-    end
-
-    def format_run_command(description, pastel)
-      @output.write_line(pastel.cyan("  [run]    #{description.lines.first.strip}"))
-      description.lines[1..].each do |line|
-        @output.write_line("           > #{line.strip}") unless line.strip.empty?
-      end
-    end
   end
 end

data/lib/kdeploy/dsl.rb

@@ -1,8 +1,27 @@
 # frozen_string_literal: true
 
 require 'set'
+require 'shellwords'
 
 module Kdeploy
+  # Helper for template resource block: captures source and variables
+  class TemplateOptions
+    def initialize
+      @source = nil
+      @variables = {}
+    end
+
+    def variables(val = nil)
+      @variables = val if val
+      @variables
+    end
+
+    def source(val = nil)
+      @source = val if val
+      @source
+    end
+  end
+
   # Domain-specific language for defining hosts, roles, and tasks
   module DSL
     def self.included(base)
@@ -154,6 +173,60 @@ module Kdeploy
       }
     end
 
+    # -------------------------------------------------------------------------
+    # Chef-style resource DSL (compiles to run/upload/upload_template)
+    # -------------------------------------------------------------------------
+
+    # 安装系统包。默认 apt 平台；支持 platform: :yum。
+    def package(name, version: nil, platform: :apt)
+      @kdeploy_commands ||= []
+      cmd = build_package_command(name, version, platform)
+      @kdeploy_commands << { type: :run, command: cmd, sudo: true }
+    end
+
+    # 管理系统服务（systemd）。action 支持 :start, :stop, :restart, :reload, :enable, :disable。
+    def service(name, action: :start)
+      @kdeploy_commands ||= []
+      actions = Array(action)
+      actions.each do |a|
+        cmd = "systemctl #{a} #{Shellwords.escape(name.to_s)}"
+        @kdeploy_commands << { type: :run, command: cmd, sudo: true }
+      end
+    end
+
+    # 部署 ERB 模板到远程路径。支持 block 或关键字参数。
+    def template(destination, source: nil, variables: nil, &block)
+      @kdeploy_commands ||= []
+      if block
+        opts = TemplateOptions.new
+        opts.instance_eval(&block)
+        src = opts.source || raise(ArgumentError, 'template requires source')
+        vars = opts.variables || {}
+      else
+        raise ArgumentError, 'template requires source' unless source
+
+        src = source
+        vars = variables || {}
+      end
+      upload_template(src, destination, vars)
+    end
+
+    # 上传本地文件到远程路径。
+    def file(destination, source:)
+      @kdeploy_commands ||= []
+      upload(source, destination)
+    end
+
+    # 确保远程目录存在。支持 mode 参数。
+    def directory(path, mode: nil)
+      @kdeploy_commands ||= []
+      cmd = "mkdir -p #{Shellwords.escape(path.to_s)}"
+      @kdeploy_commands << { type: :run, command: cmd, sudo: true }
+      return unless mode
+
+      @kdeploy_commands << { type: :run, command: "chmod #{mode} #{Shellwords.escape(path.to_s)}", sudo: true }
+    end
+
     def inventory(&block)
       instance_eval(&block) if block_given?
     end
@@ -188,5 +261,20 @@ module Kdeploy
         end
       end
     end
+
+    def build_package_command(name, version, platform)
+      n = Shellwords.escape(name.to_s)
+      case platform.to_sym
+      when :yum, :rpm
+        if version
+          "yum install -y #{n}-#{Shellwords.escape(version.to_s)}"
+        else
+          "yum install -y #{n}"
+        end
+      else
+        base = "apt-get update && apt-get install -y #{n}"
+        version ? "#{base}=#{Shellwords.escape(version.to_s)}" : base
+      end
+    end
   end
 end

data/lib/kdeploy/errors.rb

@@ -20,12 +20,16 @@ module Kdeploy
 
   # Raised when SSH operation fails
   class SSHError < Error
-    def initialize(message, original_error = nil)
+    def initialize(message, original_error = nil, command: nil, exit_status: nil, stdout: nil, stderr: nil)
       super("SSH operation failed: #{message}")
       @original_error = original_error
+      @command = command
+      @exit_status = exit_status
+      @stdout = stdout
+      @stderr = stderr
     end
 
-    attr_reader :original_error
+    attr_reader :original_error, :command, :exit_status, :stdout, :stderr
   end
 
   # Raised when SCP operation fails