kdeploy 1.3.1 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 782163100dc54c6588d66c1655434a9ab4f6a0cd3aa5d97583e4b9e5fb757bbd
-  data.tar.gz: 38c8a9e92920dcdbfdca974a9ed4a51579cb618cc2a80fedcdaf19f0fe73fd80
+  metadata.gz: bd3c4b1e7ad1dc2062bfa0e732144b64f0c3c81655320dc96defeaed10816392
+  data.tar.gz: 2ac13e3f6b7093042d4a313c139ad997e59e06b1fa2d6dc7372dc33919f3eebc
 SHA512:
-  metadata.gz: bcf659df1c65bfc50c0ebdb57a7b9f689a74c9db7107f7d3c48beb869b37633b2b887f02ca27f8f0b1707c5a593b8727e0416754221654c31faeaa1c1ddc2a3c
-  data.tar.gz: 2fa594ddb0cf3196dc1abcfd9ae9fb54729b91907445912a0e10cd4aa5d7da83c42ac9dbab02ee33e8d824b38ef25408f35e7791108e9b26728a1b96507bd816
+  metadata.gz: f224afb29cf1d419a80aa7797841b1fd935030841c0f80ad403e25573635e45956b8779c6518f6c37b4150c110c19f200baa1247ea03353e442ba6e0a5061a65
+  data.tar.gz: d6cae91436717b81f3a527707f7bed7e93107d868bf457b3ec9e62d859b42b241103f8600315155fd5e9409a09671319f487f7e0e4ea0f276d9dd8a48cd3ec2a

data/README.md

@@ -209,6 +209,8 @@ kdeploy execute deploy.rb deploy_web
 - `--retry-delay SECONDS`: 每次重试间隔秒数（默认 `1`）
 - `--retry-on-nonzero`: 非零退出码重试开关（默认 `false`）
 - `--timeout SECONDS`: 单 host 执行超时（秒，默认不启用）
+- `--step-timeout SECONDS`: 单 step 执行超时（秒，默认不启用）
+- `--retry-policy JSON`: 重试策略 JSON（覆盖 `.kdeploy.yml`）
 
 **示例:**
 ```bash
@@ -236,6 +238,15 @@ kdeploy execute deploy.rb deploy_web --retries 2 --retry-on-nonzero
 # 设置单 host 超时（秒）
 kdeploy execute deploy.rb deploy_web --timeout 120
 
+# 设置单 step 超时（秒）
+kdeploy execute deploy.rb deploy_web --step-timeout 30
+
+# 使用 CLI 覆盖重试策略（JSON）
+kdeploy execute deploy.rb deploy_web --retry-policy '{"run":{"retries":2,"retry_on_exit_codes":[2]}}'
+
+# 使用文件覆盖重试策略（JSON）
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+
 # 组合选项
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```
@@ -509,6 +520,14 @@ sync "./app", "/var/www/app",
 # 排除特定文件（与 ignore 相同，但语义更清晰）
 sync "./config", "/etc/app",
   exclude: ["*.example", "*.bak", ".env.local"]
+
+# 启用快速同步（本地/远端均有 rsync 时优先使用）
+sync "./app", "/var/www/app",
+  fast: true
+
+# 设置同步并行度
+sync "./app", "/var/www/app",
+  parallel: 4
 ```
 
 **参数:**
@@ -517,6 +536,8 @@ sync "./config", "/etc/app",
 - `ignore`: 要忽略的文件/目录模式数组（支持 .gitignore 风格的通配符）
 - `exclude`: 与 `ignore` 相同，用于语义清晰
 - `delete`: 布尔值，是否删除远程目录中不存在于源目录的文件（默认: false）
+- `fast`: 布尔值，启用快速同步路径（优先 rsync，默认: false）
+- `parallel`: 上传并行度（默认: 1）
 
 **忽略模式支持:**
 - `*.log` - 匹配所有 .log 文件
@@ -690,10 +711,24 @@ export KDEPLOY_SSH_TIMEOUT=60
 parallel: 5
 ssh_timeout: 60
 verify_host_key: true
+retries: 2
+retry_delay: 1
+retry_on_nonzero: false
+step_timeout: 30
+sync_fast: false
+sync_parallel: 4
+retry_policy:
+  run:
+    retries: 2
+    retry_on_exit_codes: [2, 255]
+  upload:
+    retries: 0
 ```
 
 配置文件会自动从当前目录向上查找，直到找到 `.kdeploy.yml` 文件。
 
+**重试策略示例文件**: `retry_policy.example.json`
+
 ## 🔧 高级用法
 
 ### 条件执行
@@ -710,6 +745,16 @@ task :deploy do
 end
 ```
 
+### 重试策略示例
+
+你可以通过文件覆盖重试策略：
+
+```bash
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+```
+
+示例文件见：`retry_policy.example.json` / `retry_policy.example.yml`
+
 ### 循环主机
 
 ```ruby

data/README_EN.md

@@ -208,6 +208,9 @@ kdeploy execute deploy.rb deploy_web
 - `--retry-delay SECONDS`: Delay between retries in seconds (default `1`)
 - `--retry-on-nonzero`: Retry commands on nonzero exit status (default `false`)
 - `--timeout SECONDS`: Per-host execution timeout in seconds (default: none)
+- `--step-timeout SECONDS`: Per-step execution timeout in seconds (default: none)
+- `--retry-policy JSON`: Retry policy JSON (overrides `.kdeploy.yml`)
+- `--retry-policy-file PATH`: Retry policy JSON file (overrides `.kdeploy.yml`)
 
 **Examples:**
 ```bash
@@ -235,6 +238,15 @@ kdeploy execute deploy.rb deploy_web --retries 2 --retry-on-nonzero
 # Set per-host timeout (seconds)
 kdeploy execute deploy.rb deploy_web --timeout 120
 
+# Set per-step timeout (seconds)
+kdeploy execute deploy.rb deploy_web --step-timeout 30
+
+# Override retry policy via CLI JSON
+kdeploy execute deploy.rb deploy_web --retry-policy '{"run":{"retries":2,"retry_on_exit_codes":[2]}}'
+
+# Override retry policy via file
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+
 # Combine options
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```
@@ -488,6 +500,45 @@ upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
 - `destination`: Remote file path
 - `variables`: Hash of variables for template rendering
 
+#### `sync` - Directory Sync
+
+Recursively sync a local directory to a remote server with filtering options.
+
+```ruby
+# Basic sync
+sync "./app", "/var/www/app"
+
+# Ignore specific files/dirs
+sync "./app", "/var/www/app",
+  ignore: [".git", "*.log", "node_modules", "*.tmp"]
+
+# Delete remote files not present locally
+sync "./app", "/var/www/app",
+  ignore: [".git", "*.log"],
+  delete: true
+
+# Exclude files (alias of ignore)
+sync "./config", "/etc/app",
+  exclude: ["*.example", "*.bak", ".env.local"]
+
+# Fast sync (prefer rsync when available)
+sync "./app", "/var/www/app",
+  fast: true
+
+# Parallel sync uploads
+sync "./app", "/var/www/app",
+  parallel: 4
+```
+
+**Parameters:**
+- `source`: Local source directory path
+- `destination`: Remote destination directory path
+- `ignore`: Patterns to ignore (gitignore-style)
+- `exclude`: Same as `ignore` for clarity
+- `delete`: Delete remote files not present locally (default: false)
+- `fast`: Enable fast sync path (prefer rsync when available, default: false)
+- `parallel`: Upload concurrency for sync (default: 1)
+
 ### 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`).
@@ -647,7 +698,21 @@ For project-specific configuration, create a `.kdeploy.yml`:
 parallel: 5
 ssh_timeout: 60
 verify_host_key: true
-```
+retries: 2
+retry_delay: 1
+retry_on_nonzero: false
+step_timeout: 30
+sync_fast: false
+sync_parallel: 4
+retry_policy:
+  run:
+    retries: 2
+    retry_on_exit_codes: [2, 255]
+  upload:
+    retries: 0
+```
+
+**Retry policy example file**: `retry_policy.example.json`
 
 ## 🔧 Advanced Usage
 
@@ -665,6 +730,16 @@ task :deploy do
 end
 ```
 
+### Retry Policy Example
+
+You can override retry policy via file:
+
+```bash
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+```
+
+Example files: `retry_policy.example.json` / `retry_policy.example.yml`
+
 ### Looping Over Hosts
 
 ```ruby
@@ -1131,7 +1206,8 @@ end
 task :deploy_app, roles: :web do
   sync "./app", "/var/www/app",
     ignore: [".git", "*.log", "node_modules", ".env.local", "*.tmp"],
-    delete: true
+    delete: true,
+    fast: true # prefer rsync when available
   sync "./config", "/etc/app", exclude: ["*.example", "*.bak"]
   service "app", action: :restart
 end

data/lib/kdeploy/{cli.rb → cli/cli.rb}

@@ -2,6 +2,7 @@
 
 require 'thor'
 require 'json'
+require 'yaml'
 require 'pastel'
 require 'tty-table'
 require 'tty-box'
@@ -53,6 +54,9 @@ module Kdeploy
     method_option :retry_delay, type: :numeric, desc: 'Retry delay seconds (default: 1)'
     method_option :retry_on_nonzero, type: :boolean, desc: 'Retry commands on nonzero exit status (default: false)'
     method_option :timeout, type: :numeric, desc: 'Per-host execution timeout seconds (default: none)'
+    method_option :step_timeout, type: :numeric, desc: 'Per-step execution timeout seconds (default: none)'
+    method_option :retry_policy, type: :string, desc: 'Retry policy JSON to override config file'
+    method_option :retry_policy_file, type: :string, desc: 'Retry policy JSON file to override config file'
     def execute(task_file, task_name = nil)
       load_config_file
       show_banner_once
@@ -77,7 +81,7 @@ module Kdeploy
 
     def load_task_file(file)
       validate_task_file(file)
-      # 用 instance_eval 并传递顶层 binding，兼容 heredoc
+      # Use module_eval with top-level binding to keep heredoc compatible
       self.class.module_eval(File.read(file), file)
     rescue StandardError => e
       raise FileNotFoundError, file if e.message.include?('not found')
@@ -272,6 +276,8 @@ module Kdeploy
       retry_on_nonzero =
         options[:retry_on_nonzero].nil? ? Configuration.default_retry_on_nonzero : options[:retry_on_nonzero]
       host_timeout = options[:timeout].nil? ? Configuration.default_host_timeout : options[:timeout]
+      step_timeout = options[:step_timeout].nil? ? Configuration.default_step_timeout : options[:step_timeout]
+      retry_policy = resolve_retry_policy
       base_dir = @task_file_dir
       runner = Runner.new(
         hosts, self.class.kdeploy_tasks,
@@ -282,7 +288,9 @@ module Kdeploy
         retries: retries,
         retry_delay: retry_delay,
         retry_on_nonzero: retry_on_nonzero,
-        host_timeout: host_timeout
+        host_timeout: host_timeout,
+        step_timeout: step_timeout,
+        retry_policy: retry_policy
       )
       results = runner.run(task)
       if options[:format] == 'json'
@@ -370,15 +378,13 @@ module Kdeploy
         duration: step[:duration]
       }
 
-      out[:exit_status] = step[:output][:exit_status] if step[:output].is_a?(Hash) && step[:output].key?(:exit_status)
-
-      out[:result] = step[:result] if step[:type] == :sync
-
-      if options[:debug] && step[:type] == :run && step[:output].is_a?(Hash)
+      if step[:output].is_a?(Hash)
         out[:stdout] = step[:output][:stdout]
         out[:stderr] = step[:output][:stderr]
+        out[:exit_status] = step[:output][:exit_status]
       end
 
+      out[:result] = step[:result] if step[:type] == :sync
       out
     end
 
@@ -397,7 +403,9 @@ module Kdeploy
           destination: cmd[:destination],
           ignore: cmd[:ignore] || [],
           exclude: cmd[:exclude] || [],
-          delete: cmd[:delete] || false
+          delete: cmd[:delete] || false,
+          fast: cmd[:fast],
+          parallel: cmd[:parallel]
         }
       else
         { type: cmd[:type].to_s }
@@ -409,11 +417,61 @@ module Kdeploy
 
       if result[:output].is_a?(Array)
         result[:output].map do |o|
-          o[:output][:stderr] if o[:output].is_a?(Hash)
+          next unless o.is_a?(Hash)
+
+          err = o[:output]
+          next unless err.is_a?(Hash)
+
+          pieces = []
+          pieces << "command=#{err[:command]}" if err[:command]
+          pieces << "exit_status=#{err[:exit_status]}" if err[:exit_status]
+          pieces << "stderr=#{err[:stderr]}" if err[:stderr]
+          pieces.join(' ')
         end.compact.join("\n")
       else
         result[:output].to_s
       end
     end
+
+    def parse_retry_policy(raw)
+      policy = JSON.parse(raw)
+      raise ArgumentError, 'retry_policy must be a JSON object' unless policy.is_a?(Hash)
+
+      policy
+    rescue JSON::ParserError => e
+      raise ArgumentError, "retry_policy JSON parse error: #{e.message}"
+    end
+
+    def resolve_retry_policy
+      if options[:retry_policy_file]
+        path = options[:retry_policy_file]
+        unless File.exist?(path)
+          raise ArgumentError,
+                "retry_policy file not found: #{path} (examples: retry_policy.example.json / retry_policy.example.yml)"
+        end
+
+        return parse_retry_policy_file(path)
+      end
+      return parse_retry_policy(options[:retry_policy]) if options[:retry_policy]
+
+      Configuration.default_retry_policy
+    end
+
+    def parse_retry_policy_file(path)
+      ext = File.extname(path).downcase
+      raw = File.read(path)
+      policy =
+        case ext
+        when '.yml', '.yaml'
+          YAML.safe_load(raw) || {}
+        else
+          JSON.parse(raw)
+        end
+      raise ArgumentError, 'retry_policy must be a JSON/YAML object' unless policy.is_a?(Hash)
+
+      policy
+    rescue JSON::ParserError, Psych::SyntaxError => e
+      raise ArgumentError, "retry_policy parse error: #{e.message}"
+    end
   end
 end

data/lib/kdeploy/{help_formatter.rb → cli/help_formatter.rb}

@@ -36,6 +36,9 @@ module Kdeploy
         #{@pastel.dim('    --retry-delay SECONDS')}      Retry delay seconds (default: 1; overridden by .kdeploy.yml)
         #{@pastel.dim('    --retry-on-nonzero')}         Retry commands on nonzero exit status (default: false; overridden by .kdeploy.yml)
         #{@pastel.dim('    --timeout SECONDS')}          Per-host execution timeout seconds (default: none; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --step-timeout SECONDS')}     Per-step execution timeout seconds (default: none; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --retry-policy JSON')}        Retry policy JSON (overrides .kdeploy.yml)
+        #{@pastel.dim('    --retry-policy-file PATH')}   Retry policy JSON file (overrides .kdeploy.yml)
 
         #{@pastel.bright_yellow('🆕')} #{@pastel.bright_white('init [DIR]')}                  Initialize new deployment project
         #{@pastel.bright_yellow('ℹ️')} #{@pastel.bright_white('version')}                    Show version information

data/lib/kdeploy/{configuration.rb → config/configuration.rb}

@@ -12,6 +12,10 @@ module Kdeploy
     DEFAULT_RETRY_DELAY = 1
     DEFAULT_HOST_TIMEOUT = nil
     DEFAULT_RETRY_ON_NONZERO = false
+    DEFAULT_SYNC_FAST = false
+    DEFAULT_STEP_TIMEOUT = nil
+    DEFAULT_RETRY_POLICY = nil
+    DEFAULT_SYNC_PARALLEL = 1
     CONFIG_FILE_NAME = '.kdeploy.yml'
 
     class << self
@@ -21,7 +25,11 @@ module Kdeploy
                     :default_retries,
                     :default_retry_delay,
                     :default_host_timeout,
-                    :default_retry_on_nonzero
+                    :default_retry_on_nonzero,
+                    :default_sync_fast,
+                    :default_step_timeout,
+                    :default_retry_policy,
+                    :default_sync_parallel
 
       def reset
         @default_parallel = DEFAULT_PARALLEL
@@ -31,6 +39,10 @@ module Kdeploy
         @default_retry_delay = DEFAULT_RETRY_DELAY
         @default_host_timeout = DEFAULT_HOST_TIMEOUT
         @default_retry_on_nonzero = DEFAULT_RETRY_ON_NONZERO
+        @default_sync_fast = DEFAULT_SYNC_FAST
+        @default_step_timeout = DEFAULT_STEP_TIMEOUT
+        @default_retry_policy = DEFAULT_RETRY_POLICY
+        @default_sync_parallel = DEFAULT_SYNC_PARALLEL
       end
 
       def load_from_file(config_path = nil)
@@ -72,6 +84,10 @@ module Kdeploy
         @default_retry_delay = config['retry_delay'] if config.key?('retry_delay')
         @default_host_timeout = config['host_timeout'] if config.key?('host_timeout')
         @default_retry_on_nonzero = config['retry_on_nonzero'] if config.key?('retry_on_nonzero')
+        @default_sync_fast = config['sync_fast'] if config.key?('sync_fast')
+        @default_step_timeout = config['step_timeout'] if config.key?('step_timeout')
+        @default_retry_policy = config['retry_policy'] if config.key?('retry_policy')
+        @default_sync_parallel = config['sync_parallel'] if config.key?('sync_parallel')
       end
 
       def parse_verify_host_key(value)

data/lib/kdeploy/{dsl.rb → dsl/dsl.rb}

@@ -161,7 +161,7 @@ module Kdeploy
       }
     end
 
-    def sync(source, destination, ignore: [], delete: false, exclude: [])
+    def sync(source, destination, ignore: [], delete: false, exclude: [], fast: nil, parallel: nil)
       @kdeploy_commands ||= []
       @kdeploy_commands << {
         type: :sync,
@@ -169,7 +169,9 @@ module Kdeploy
         destination: destination,
         ignore: Array(ignore),
         exclude: Array(exclude),
-        delete: delete
+        delete: delete,
+        fast: fast,
+        parallel: parallel
       }
     end
 
@@ -177,14 +179,14 @@ module Kdeploy
     # Chef-style resource DSL (compiles to run/upload/upload_template)
     # -------------------------------------------------------------------------
 
-    # 安装系统包。默认 apt 平台；支持 platform: :yum。
+    # Install a system package. Defaults to apt; supports 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。
+    # Manage a systemd service. action supports :start, :stop, :restart, :reload, :enable, :disable.
     def service(name, action: :start)
       @kdeploy_commands ||= []
       actions = Array(action)
@@ -194,7 +196,7 @@ module Kdeploy
       end
     end
 
-    # 部署 ERB 模板到远程路径。支持 block 或关键字参数。
+    # Deploy an ERB template to a remote path. Supports block and keyword args.
     def template(destination, source: nil, variables: nil, &block)
       @kdeploy_commands ||= []
       if block
@@ -211,13 +213,13 @@ module Kdeploy
       upload_template(src, destination, vars)
     end
 
-    # 上传本地文件到远程路径。
+    # Upload a local file to a remote path.
     def file(destination, source:)
       @kdeploy_commands ||= []
       upload(source, destination)
     end
 
-    # 确保远程目录存在。支持 mode 参数。
+    # Ensure a remote directory exists. Supports mode option.
     def directory(path, mode: nil)
       @kdeploy_commands ||= []
       cmd = "mkdir -p #{Shellwords.escape(path.to_s)}"

data/lib/kdeploy/{initializer.rb → dsl/initializer.rb}

@@ -96,11 +96,11 @@ module Kdeploy
     end
 
     def create_config_files
-      # 创建配置目录
+      # Create config directory
       config_dir = File.join(@target_dir, 'config')
       FileUtils.mkdir_p(config_dir)
 
-      # 创建 Nginx ERB 模板
+      # Create Nginx ERB template
       File.write(File.join(config_dir, 'nginx.conf.erb'), <<~CONF)
         user nginx;
         worker_processes <%= worker_processes %>;
@@ -152,7 +152,7 @@ module Kdeploy
         }
       CONF
 
-      # 创建静态配置文件示例
+      # Create static config file example
       File.write(File.join(config_dir, 'app.conf'), <<~CONF)
         location /api {
             proxy_pass http://localhost:3000;

data/lib/kdeploy/errors.rb

@@ -52,6 +52,13 @@ module Kdeploy
     attr_reader :original_error
   end
 
+  # Raised when a step exceeds configured timeout
+  class StepTimeoutError < Error
+    def initialize(message)
+      super("Step timeout: #{message}")
+    end
+  end
+
   # Raised when configuration is invalid
   class ConfigurationError < Error
     def initialize(message)

data/lib/kdeploy/executor/command_executor.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Kdeploy
+  # Executes a single command and records execution time
+  class CommandExecutor
+    def initialize(executor, output, debug: false, retries: 0, retry_delay: 1, retry_on_nonzero: false,
+                   step_timeout: nil, retry_policy: nil)
+      @executor = executor
+      @output = output
+      @debug = debug
+      @retries = retries.to_i
+      @retry_delay = retry_delay.to_f
+      @retry_on_nonzero = retry_on_nonzero
+      @step_timeout = step_timeout&.to_f
+      @retry_policy = retry_policy
+    end
+
+    def execute_run(command, _host_name)
+      cmd = command[:command]
+      use_sudo = command[:sudo]
+
+      result, duration = measure_time do
+        with_retries(step_type: :run) do
+          with_timeout { @executor.execute(cmd, use_sudo: use_sudo) }
+        end
+      end
+
+      { command: cmd, output: result, duration: duration, type: :run }
+    end
+
+    def execute_upload(command, _host_name)
+      _result, duration = measure_time do
+        with_retries(step_type: :upload) do
+          with_timeout { @executor.upload(command[:source], command[:destination]) }
+        end
+      end
+      {
+        command: "upload: #{command[:source]} -> #{command[:destination]}",
+        duration: duration,
+        type: :upload
+      }
+    end
+
+    def execute_upload_template(command, _host_name)
+      _result, duration = measure_time do
+        with_retries(step_type: :upload_template) do
+          with_timeout do
+            @executor.upload_template(command[:source], command[:destination], command[:variables])
+          end
+        end
+      end
+      {
+        command: "upload_template: #{command[:source]} -> #{command[:destination]}",
+        duration: duration,
+        type: :upload_template
+      }
+    end
+
+    def execute_sync(command, _host_name)
+      source = command[:source]
+      destination = command[:destination]
+      fast = command.key?(:fast) ? command[:fast] : Configuration.default_sync_fast
+      parallel = command.key?(:parallel) ? command[:parallel] : Configuration.default_sync_parallel
+
+      result, duration = measure_time do
+        with_retries(step_type: :sync) do
+          with_timeout do
+            @executor.sync_directory(
+              source,
+              destination,
+              ignore: command[:ignore] || [],
+              exclude: command[:exclude] || [],
+              delete: command[:delete] || false,
+              fast: fast,
+              parallel: parallel
+            )
+          end
+        end
+      end
+
+      build_sync_result(source, destination, result, duration)
+    end
+
+    private
+
+    def build_sync_result(source, destination, result, duration)
+      {
+        command: "sync: #{source} -> #{destination}",
+        duration: duration,
+        type: :sync,
+        result: result,
+        uploaded: result[:uploaded],
+        deleted: result[:deleted],
+        total: result[:total]
+      }
+    end
+
+    def measure_time
+      start_time = Time.now
+      result = yield
+      duration = Time.now - start_time
+      [result, duration]
+    end
+
+    def with_retries(step_type: nil)
+      attempts = 0
+      max_retries = retries_for(step_type)
+      exit_codes = retry_exit_codes_for(step_type)
+      begin
+        attempts += 1
+        yield
+      rescue SSHError, SCPError, TemplateError => e
+        raise if e.is_a?(SSHError) && e.exit_status && !retry_on_exit_status?(e.exit_status, exit_codes)
+        raise if attempts > (max_retries + 1)
+
+        sleep(@retry_delay) if @retry_delay.positive?
+        retry
+      end
+    end
+
+    def with_timeout(&block)
+      return yield unless @step_timeout&.positive?
+
+      Timeout.timeout(@step_timeout, &block)
+    rescue Timeout::Error
+      raise StepTimeoutError, "exceeded #{@step_timeout}s"
+    end
+
+    def retries_for(step_type)
+      return @retries unless @retry_policy.is_a?(Hash) && step_type
+
+      policy = @retry_policy[step_type.to_s] || @retry_policy[step_type.to_sym]
+      return @retries unless policy.is_a?(Hash)
+
+      policy.fetch('retries', policy.fetch(:retries, @retries)).to_i
+    end
+
+    def retry_exit_codes_for(step_type)
+      return nil unless @retry_policy.is_a?(Hash) && step_type
+
+      policy = @retry_policy[step_type.to_s] || @retry_policy[step_type.to_sym]
+      return nil unless policy.is_a?(Hash)
+
+      policy['retry_on_exit_codes'] || policy[:retry_on_exit_codes]
+    end
+
+    def retry_on_exit_status?(exit_status, exit_codes)
+      return @retry_on_nonzero if exit_codes.nil?
+
+      Array(exit_codes).map(&:to_i).include?(exit_status.to_i)
+    end
+  end
+end

data/lib/kdeploy/{executor.rb → executor/executor.rb}

@@ -5,6 +5,8 @@ require 'net/scp'
 require 'pathname'
 require 'find'
 require 'shellwords'
+require 'tempfile'
+require 'concurrent'
 require_relative 'file_filter'
 
 module Kdeploy
@@ -16,7 +18,7 @@ module Kdeploy
       @ip = host_config[:ip]
       @password = host_config[:password]
       @key = host_config[:key]
-      @port = host_config[:port] # 新增端口支持
+      @port = host_config[:port] # Added custom port support
       @use_sudo = host_config[:use_sudo] || false
       @sudo_password = host_config[:sudo_password]
       @base_dir = host_config[:base_dir] # Base directory for resolving relative paths
@@ -114,7 +116,8 @@ module Kdeploy
       raise TemplateError.new("Template upload failed: #{e.message}", e)
     end
 
-    def sync_directory(source, destination, ignore: [], exclude: [], delete: false, use_sudo: nil)
+    def sync_directory(source, destination, ignore: [], exclude: [], delete: false, fast: nil, parallel: nil,
+                       use_sudo: nil)
       use_sudo = @use_sudo if use_sudo.nil?
 
       # Resolve relative paths relative to base_dir
@@ -127,24 +130,29 @@ module Kdeploy
       all_patterns = ignore + exclude
       filter = FileFilter.new(ignore_patterns: all_patterns)
 
+      if fast
+        rsync_result = sync_with_rsync(
+          resolved_source,
+          destination,
+          ignore: ignore,
+          exclude: exclude,
+          delete: delete,
+          use_sudo: use_sudo
+        )
+        return rsync_result if rsync_result
+      end
+
       # Collect files to sync
       files_to_sync = collect_files_to_sync(resolved_source, filter)
 
       # Upload files
-      uploaded_count = 0
-      source_path = Pathname.new(resolved_source)
-      files_to_sync.each do |file_path|
-        relative_path = Pathname.new(file_path).relative_path_from(source_path).to_s
-        remote_path = File.join(destination, relative_path).gsub(%r{/+}, '/')
-
-        # Ensure remote directory exists
-        remote_dir = File.dirname(remote_path)
-        ensure_remote_directory(remote_dir, use_sudo: use_sudo)
-
-        # Upload file
-        upload(file_path, remote_path, use_sudo: use_sudo)
-        uploaded_count += 1
-      end
+      uploaded_count = upload_files(
+        files_to_sync,
+        resolved_source,
+        destination,
+        parallel: parallel,
+        use_sudo: use_sudo
+      )
 
       # Delete extra files if requested
       deleted_count = 0
@@ -196,6 +204,80 @@ module Kdeploy
       end
     end
 
+    def sync_with_rsync(source, destination, ignore:, exclude:, delete:, use_sudo:)
+      return nil unless system('command -v rsync >/dev/null 2>&1')
+
+      exclude_file = build_rsync_excludes(ignore + exclude)
+
+      unless remote_rsync_available?
+        File.delete(exclude_file) if exclude_file && File.exist?(exclude_file)
+        return nil
+      end
+
+      begin
+        rsync_cmd = build_rsync_command(source, destination, exclude_file, delete: delete, use_sudo: use_sudo)
+        return nil unless system(rsync_cmd)
+
+        {
+          uploaded: 0,
+          deleted: 0,
+          total: 0,
+          fast_path: 'rsync'
+        }
+      ensure
+        File.delete(exclude_file) if exclude_file && File.exist?(exclude_file)
+      end
+    rescue StandardError
+      nil
+    end
+
+    def build_rsync_excludes(patterns)
+      patterns = Array(patterns).compact
+      return nil if patterns.empty?
+
+      file = Tempfile.new('kdeploy_rsync_excludes')
+      patterns.each { |pattern| file.write("#{pattern}\n") }
+      file.close
+      file.path
+    end
+
+    def build_rsync_command(source, destination, exclude_file, delete:, use_sudo:)
+      delete_flag = delete ? '--delete' : ''
+      exclude_flag = exclude_file ? "--exclude-from='#{exclude_file}'" : ''
+      ssh_cmd = build_rsync_ssh_command
+      sudo_flag = if use_sudo || requires_sudo?(destination)
+                    '--rsync-path="sudo rsync"'
+                  else
+                    ''
+                  end
+      parts = [
+        'rsync -az',
+        delete_flag,
+        exclude_flag,
+        sudo_flag,
+        "-e \"#{ssh_cmd}\"",
+        "#{Shellwords.escape(source)}/",
+        "#{@user}@#{@ip}:#{Shellwords.escape(destination)}/"
+      ].reject(&:empty?)
+      parts.join(' ')
+    end
+
+    def build_rsync_ssh_command
+      ssh = ['ssh']
+      ssh << "-p #{@port}" if @port
+      ssh << "-i #{Shellwords.escape(@key)}" if @key
+      ssh.join(' ')
+    end
+
+    def remote_rsync_available?
+      Net::SSH.start(@ip, @user, ssh_options) do |ssh|
+        output = ssh.exec!('command -v rsync 2>/dev/null || true')
+        return !output.to_s.strip.empty?
+      end
+    rescue StandardError
+      false
+    end
+
     def requires_sudo?(path)
       # Check if path is in system directories that typically require sudo
       system_dirs = %w[/etc /usr /var /opt /sbin /bin /lib /lib64 /root]
@@ -229,16 +311,16 @@ module Kdeploy
     end
 
     def wrap_with_sudo(command)
-      # 如果命令已经以 sudo 开头，不重复添加
+      # Do not add sudo again if command already starts with sudo
       return command if command.strip.start_with?('sudo')
 
-      # 多行、shell 控制结构、或包含 && / || / ; 的复合命令需整段在 sudo 下执行
+      # Wrap multi-line/control/compound commands so sudo applies to the full block
       needs_wrap = command.include?("\n") ||
                    command.match?(/\b(if|for|while|case|function)\b/) ||
                    command.match?(/\s(&&|\|\||;)\s/)
 
       if needs_wrap
-        # 转义命令中的单引号，然后用 bash -c 执行
+        # Escape single quotes in command, then execute via bash -c
         escaped_command = command.gsub("'", "'\"'\"'")
         if @sudo_password
           escaped_password = @sudo_password.gsub('\'', "'\"'\"'").gsub('$', '\\$').gsub('`', '\\`')
@@ -247,7 +329,7 @@ module Kdeploy
           "sudo bash -c '#{escaped_command}'"
         end
       elsif @sudo_password
-        # 单行命令直接包装
+        # Wrap single-line command directly
         escaped_password = @sudo_password.gsub('\'', "'\"'\"'").gsub('$', '\\$').gsub('`', '\\`')
         "echo '#{escaped_password}' | sudo -S #{command}"
       else
@@ -271,6 +353,55 @@ module Kdeploy
       files
     end
 
+    def upload_files(files_to_sync, source_dir, destination, parallel:, use_sudo:)
+      count = Concurrent::AtomicFixnum.new(0)
+      source_path = Pathname.new(source_dir)
+      parallel = normalize_parallel(parallel)
+      return upload_files_sequential(files_to_sync, source_path, destination, use_sudo, count) if parallel <= 1
+
+      queue = Queue.new
+      files_to_sync.each { |path| queue << path }
+      workers = Array.new(parallel) do
+        Thread.new do
+          until queue.empty?
+            file_path = begin
+              queue.pop(true)
+            rescue StandardError
+              nil
+            end
+            next unless file_path
+
+            upload_single_file(file_path, source_path, destination, use_sudo)
+            count.increment
+          end
+        end
+      end
+      workers.each(&:join)
+      count.value
+    end
+
+    def upload_files_sequential(files_to_sync, source_path, destination, use_sudo, count)
+      files_to_sync.each do |file_path|
+        upload_single_file(file_path, source_path, destination, use_sudo)
+        count.increment
+      end
+      count.value
+    end
+
+    def upload_single_file(file_path, source_path, destination, use_sudo)
+      relative_path = Pathname.new(file_path).relative_path_from(source_path).to_s
+      remote_path = File.join(destination, relative_path).gsub(%r{/+}, '/')
+      remote_dir = File.dirname(remote_path)
+      ensure_remote_directory(remote_dir, use_sudo: use_sudo)
+      upload(file_path, remote_path, use_sudo: use_sudo)
+    end
+
+    def normalize_parallel(parallel)
+      value = parallel.nil? ? Configuration.default_sync_parallel : parallel
+      value = value.to_i
+      value.positive? ? value : 1
+    end
+
     def ensure_remote_directory(remote_dir, use_sudo: nil)
       use_sudo = @use_sudo if use_sudo.nil?
       return if remote_dir.nil? || remote_dir.empty? || remote_dir == '.' || remote_dir == '/'

data/lib/kdeploy/{output_formatter.rb → output/output_formatter.rb}

@@ -261,6 +261,7 @@ module Kdeploy
       stats = []
       stats << @pastel.green("#{uploaded} uploaded") if uploaded.positive?
       stats << @pastel.yellow("#{deleted} deleted") if deleted.positive?
+      stats << @pastel.cyan("fast: #{result[:fast_path]}") if result[:fast_path]
       stats_str = stats.any? ? " (#{stats.join(', ')})" : " (#{total} files)"
 
       @pastel.dim('    ') + @pastel.cyan(display_path) + @pastel.dim(stats_str) + duration_str + " #{status_str}"

data/lib/kdeploy/{runner.rb → runner/runner.rb}

@@ -9,7 +9,10 @@ module Kdeploy
                    debug: false, base_dir: nil, retries: Configuration.default_retries,
                    retry_delay: Configuration.default_retry_delay,
                    retry_on_nonzero: Configuration.default_retry_on_nonzero,
-                   host_timeout: Configuration.default_host_timeout)
+                   host_timeout: Configuration.default_host_timeout,
+                   step_timeout: Configuration.default_step_timeout,
+                   retry_policy: Configuration.default_retry_policy,
+                   on_step: nil)
       @hosts = hosts
       @tasks = tasks
       @parallel = parallel
@@ -20,6 +23,9 @@ module Kdeploy
       @retry_delay = retry_delay
       @retry_on_nonzero = retry_on_nonzero
       @host_timeout = normalize_timeout(host_timeout)
+      @step_timeout = normalize_timeout(step_timeout)
+      @retry_policy = retry_policy
+      @on_step = on_step
       @pool = Concurrent::FixedThreadPool.new(@parallel)
       @results = Concurrent::Hash.new
     end
@@ -102,7 +108,9 @@ module Kdeploy
         debug: @debug,
         retries: @retries,
         retry_delay: @retry_delay,
-        retry_on_nonzero: @retry_on_nonzero
+        retry_on_nonzero: @retry_on_nonzero,
+        step_timeout: @step_timeout,
+        retry_policy: @retry_policy
       )
       result = { status: :success, output: [] }
 
@@ -124,6 +132,7 @@ module Kdeploy
       commands.each do |command|
         step_result = execute_command(command_executor, command, name)
         result[:output] << step_result
+        emit_step(name, step_result, result, task_name)
       rescue StandardError => e
         step = step_description(command)
         result[:status] = :failed
@@ -135,6 +144,7 @@ module Kdeploy
           error: "#{e.class}: #{e.message}",
           output: error_output_for_step(e)
         }
+        emit_step(name, result[:output].last, result, task_name)
         break
       end
     end
@@ -208,6 +218,15 @@ module Kdeploy
       end
     end
 
+    def emit_step(host_name, step_result, result, task_name)
+      return unless @on_step
+
+      @on_step.call(host_name, step_result, result, task_name)
+    rescue StandardError
+      # Best-effort only; never fail execution because of streaming hooks.
+      nil
+    end
+
     def execute_command(command_executor, command, host_name)
       case command[:type]
       when :run

data/lib/kdeploy/{template.rb → template/template.rb}

@@ -2,12 +2,14 @@
 
 require 'erb'
 require 'tempfile'
+require 'set'
 
 module Kdeploy
   # ERB template rendering and upload handler
   class Template
     def self.render(template_path, variables = {})
       template_content = File.read(template_path)
+      validate_template_variables(template_content, variables)
       context = create_template_context(variables)
       ERB.new(template_content).result(context.instance_eval { binding })
     end
@@ -24,17 +26,38 @@ module Kdeploy
     def self.render_and_upload(executor, template_path, destination, variables = {})
       rendered_content = render(template_path, variables)
 
-      # 创建临时文件
+      # Create temporary file
       temp_file = Tempfile.new('kdeploy')
       begin
         temp_file.write(rendered_content)
         temp_file.close
 
-        # 上传渲染后的文件
+        # Upload rendered file
         executor.upload(temp_file.path, destination)
       ensure
         temp_file.unlink
       end
     end
+
+    def self.validate_template_variables(template_content, variables)
+      required = extract_template_identifiers(template_content)
+      return if required.empty?
+
+      provided = variables.keys.to_set(&:to_s)
+      missing = required.reject { |name| provided.include?(name) }
+      return if missing.empty?
+
+      raise ArgumentError, "Missing template variables: #{missing.sort.join(', ')}"
+    end
+
+    def self.extract_template_identifiers(template_content)
+      identifiers = template_content.scan(/<%=\s*([a-zA-Z_]\w*)/).flatten
+      identifiers.uniq - ruby_keywords
+    end
+
+    def self.ruby_keywords
+      %w[alias and begin break case class def defined? do else elsif end ensure false for if in module next nil not
+         or redo rescue retry return self super then true undef unless until when while yield]
+    end
   end
 end

data/lib/kdeploy/version.rb

@@ -2,5 +2,5 @@
 
 # Kdeploy module for version management
 module Kdeploy
-  VERSION = '1.3.1' unless const_defined?(:VERSION)
+  VERSION = '1.3.3' unless const_defined?(:VERSION)
 end

data/lib/kdeploy.rb

@@ -2,20 +2,20 @@
 
 require_relative 'kdeploy/version'
 require_relative 'kdeploy/errors'
-require_relative 'kdeploy/configuration'
-require_relative 'kdeploy/output'
+require_relative 'kdeploy/config/configuration'
+require_relative 'kdeploy/output/output'
 require_relative 'kdeploy/banner'
-require_relative 'kdeploy/file_filter'
-require_relative 'kdeploy/dsl'
-require_relative 'kdeploy/executor'
-require_relative 'kdeploy/command_executor'
-require_relative 'kdeploy/output_formatter'
-require_relative 'kdeploy/help_formatter'
-require_relative 'kdeploy/runner'
-require_relative 'kdeploy/initializer'
-require_relative 'kdeploy/template'
+require_relative 'kdeploy/executor/file_filter'
+require_relative 'kdeploy/dsl/dsl'
+require_relative 'kdeploy/executor/executor'
+require_relative 'kdeploy/executor/command_executor'
+require_relative 'kdeploy/output/output_formatter'
+require_relative 'kdeploy/cli/help_formatter'
+require_relative 'kdeploy/runner/runner'
+require_relative 'kdeploy/dsl/initializer'
+require_relative 'kdeploy/template/template'
 require_relative 'kdeploy/post_install'
-require_relative 'kdeploy/cli'
+require_relative 'kdeploy/cli/cli'
 
 # Kdeploy - A lightweight agentless deployment automation tool
 module Kdeploy

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kdeploy
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.3
 platform: ruby
 authors:
 - Kk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-03 00:00:00.000000000 Z
+date: 2026-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt_pbkdf
@@ -167,22 +167,22 @@ files:
 - ext/mkrf_conf.rb
 - lib/kdeploy.rb
 - lib/kdeploy/banner.rb
-- lib/kdeploy/cli.rb
-- lib/kdeploy/command_executor.rb
+- lib/kdeploy/cli/cli.rb
+- lib/kdeploy/cli/help_formatter.rb
 - lib/kdeploy/completions/kdeploy.bash
 - lib/kdeploy/completions/kdeploy.zsh
-- lib/kdeploy/configuration.rb
-- lib/kdeploy/dsl.rb
+- lib/kdeploy/config/configuration.rb
+- lib/kdeploy/dsl/dsl.rb
+- lib/kdeploy/dsl/initializer.rb
 - lib/kdeploy/errors.rb
-- lib/kdeploy/executor.rb
-- lib/kdeploy/file_filter.rb
-- lib/kdeploy/help_formatter.rb
-- lib/kdeploy/initializer.rb
-- lib/kdeploy/output.rb
-- lib/kdeploy/output_formatter.rb
+- lib/kdeploy/executor/command_executor.rb
+- lib/kdeploy/executor/executor.rb
+- lib/kdeploy/executor/file_filter.rb
+- lib/kdeploy/output/output.rb
+- lib/kdeploy/output/output_formatter.rb
 - lib/kdeploy/post_install.rb
-- lib/kdeploy/runner.rb
-- lib/kdeploy/template.rb
+- lib/kdeploy/runner/runner.rb
+- lib/kdeploy/template/template.rb
 - lib/kdeploy/version.rb
 homepage: https://github.com/kevin197011/kdeploy
 licenses:

data/lib/kdeploy/command_executor.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-module Kdeploy
-  # Executes a single command and records execution time
-  class CommandExecutor
-    def initialize(executor, output, debug: false, retries: 0, retry_delay: 1, retry_on_nonzero: false)
-      @executor = executor
-      @output = output
-      @debug = debug
-      @retries = retries.to_i
-      @retry_delay = retry_delay.to_f
-      @retry_on_nonzero = retry_on_nonzero
-    end
-
-    def execute_run(command, _host_name)
-      cmd = command[:command]
-      use_sudo = command[:sudo]
-
-      result, duration = measure_time do
-        with_retries { @executor.execute(cmd, use_sudo: use_sudo) }
-      end
-
-      { command: cmd, output: result, duration: duration, type: :run }
-    end
-
-    def execute_upload(command, _host_name)
-      _result, duration = measure_time do
-        with_retries { @executor.upload(command[:source], command[:destination]) }
-      end
-      {
-        command: "upload: #{command[:source]} -> #{command[:destination]}",
-        duration: duration,
-        type: :upload
-      }
-    end
-
-    def execute_upload_template(command, _host_name)
-      _result, duration = measure_time do
-        with_retries do
-          @executor.upload_template(command[:source], command[:destination], command[:variables])
-        end
-      end
-      {
-        command: "upload_template: #{command[:source]} -> #{command[:destination]}",
-        duration: duration,
-        type: :upload_template
-      }
-    end
-
-    def execute_sync(command, _host_name)
-      source = command[:source]
-      destination = command[:destination]
-
-      result, duration = measure_time do
-        with_retries do
-          @executor.sync_directory(
-            source,
-            destination,
-            ignore: command[:ignore] || [],
-            exclude: command[:exclude] || [],
-            delete: command[:delete] || false
-          )
-        end
-      end
-
-      build_sync_result(source, destination, result, duration)
-    end
-
-    private
-
-    def build_sync_result(source, destination, result, duration)
-      {
-        command: "sync: #{source} -> #{destination}",
-        duration: duration,
-        type: :sync,
-        result: result,
-        uploaded: result[:uploaded],
-        deleted: result[:deleted],
-        total: result[:total]
-      }
-    end
-
-    def measure_time
-      start_time = Time.now
-      result = yield
-      duration = Time.now - start_time
-      [result, duration]
-    end
-
-    def with_retries
-      attempts = 0
-      begin
-        attempts += 1
-        yield
-      rescue SSHError, SCPError, TemplateError => e
-        raise if e.is_a?(SSHError) && e.exit_status && !@retry_on_nonzero
-        raise if attempts > (@retries + 1)
-
-        sleep(@retry_delay) if @retry_delay.positive?
-        retry
-      end
-    end
-  end
-end