kdeploy 1.2.30 → 1.2.33

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb0be08200c1be7fccc54f427d3dfc8111113bde76217642cb18a5a1d7bb6ea
-  data.tar.gz: 2002567662d65d4d6927e2090b56ce88e8acfb5d64eb758c4a5b92a06bf3be95
+  metadata.gz: ba776f38e5a34ec7e6dac606aac7202391fdab2e4869aec08f526b3228bc8deb
+  data.tar.gz: aaa348b87ad83b9c8c1ad3291a2e45395594b922c1594fa82d54cd2a9b7c6d30
 SHA512:
-  metadata.gz: 2c9f208415d75f9edd4b06ec15f8ff25e730f2a2b0a8356b6d10a15db441a32a275544e8efc822edbeba28eebad3528093c2fff0baf15378a579fd508e2fe250
-  data.tar.gz: eea102b4f5628f869299258fbc775b5c95b1a3c8105cedb2dedd731915016c02714689f14015b105cf38fa39505d4e14c4aa8080fdbf36cd66760b3a1eaa685b
+  metadata.gz: 7d731fd05fddc4b03c0aaef558e5200b6584772159262405d80cf807eae5f096689201e60aad944f0dd51b2a5e0db7d1d883476ec945cd3984a19383c840830c
+  data.tar.gz: 6ce986d5b3a60685ed51340298a0d0fbe22d25c2ee7c7cf584b3870d23174d004597e5135c7bb52a2f2f1d1006806c552d49ddcdb92080808348a580ec865947

data/AGENTS.md

@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

data/README.md

@@ -201,6 +201,11 @@ kdeploy execute deploy.rb deploy_web
 - `--limit HOSTS`: 限制执行到特定主机（逗号分隔）
 - `--parallel NUM`: 并行执行数量（默认: 10）
 - `--dry-run`: 预览模式 - 显示将要执行的操作而不实际执行
+- `--debug`: 调试模式 - 显示 `run` 命令的 stdout/stderr 详细输出（便于排查问题）
+- `--no-banner`: 不输出 Banner（更适合脚本/CI 场景）
+- `--format FORMAT`: 输出格式（`text`|`json`，默认 `text`）
+- `--retries N`: 网络相关操作重试次数（默认 `0`）
+- `--retry-delay SECONDS`: 每次重试间隔秒数（默认 `1`）
 
 **示例:**
 ```bash
@@ -213,6 +218,15 @@ kdeploy execute deploy.rb deploy_web --limit web01,web02
 # 使用自定义并行数量
 kdeploy execute deploy.rb deploy_web --parallel 5
 
+# 输出详细调试信息（stdout/stderr）
+kdeploy execute deploy.rb deploy_web --debug
+
+# 机器可读 JSON 输出（便于集成）
+kdeploy execute deploy.rb deploy_web --format json --no-banner
+
+# 重试网络抖动导致的失败
+kdeploy execute deploy.rb deploy_web --retries 3 --retry-delay 1
+
 # 组合选项
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```

data/README_EN.md

@@ -200,6 +200,11 @@ kdeploy execute deploy.rb deploy_web
 - `--limit HOSTS`: Limit execution to specific hosts (comma-separated)
 - `--parallel NUM`: Number of parallel executions (default: 10)
 - `--dry-run`: Preview mode - show what would be done without executing
+- `--debug`: Debug mode - show detailed stdout/stderr output for `run` steps
+- `--no-banner`: Do not print banner (automation-friendly)
+- `--format FORMAT`: Output format (`text`|`json`, default `text`)
+- `--retries N`: Retry count for network operations (default `0`)
+- `--retry-delay SECONDS`: Delay between retries in seconds (default `1`)
 
 **Examples:**
 ```bash
@@ -212,6 +217,15 @@ kdeploy execute deploy.rb deploy_web --limit web01,web02
 # Use custom parallel count
 kdeploy execute deploy.rb deploy_web --parallel 5
 
+# Show detailed stdout/stderr output
+kdeploy execute deploy.rb deploy_web --debug
+
+# Machine-readable JSON output
+kdeploy execute deploy.rb deploy_web --format json --no-banner
+
+# Retry transient network failures
+kdeploy execute deploy.rb deploy_web --retries 3 --retry-delay 1
+
 # Combine options
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```

data/exe/kdeploy

@@ -1,19 +1,5 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# 自动修复常见 gem 扩展
-# %w[debug rbs].zip(%w[1.7.1 2.8.2]).each do |gem_name, version|
-#   require gem_name
-# rescue LoadError
-#   warn "[Kdeploy] 自动修复 #{gem_name}-#{version} ..."
-#   system("gem pristine #{gem_name} --version #{version}")
-#   begin
-#     require gem_name
-#   rescue LoadError
-#     warn "[Kdeploy] 依然无法加载 #{gem_name}-#{version}，请手动修复。"
-#   end
-# end
-
 require 'kdeploy'
-
 Kdeploy::CLI.start(ARGV)

data/lib/kdeploy/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'thor'
+require 'json'
 require 'pastel'
 require 'tty-table'
 require 'tty-box'
@@ -43,9 +44,13 @@ module Kdeploy
 
     desc 'execute TASK_FILE [TASK]', 'Execute deployment tasks from file'
     method_option :limit, type: :string, desc: 'Limit to specific hosts (comma-separated)'
-    method_option :parallel, type: :numeric, default: 10, desc: 'Number of parallel executions'
+    method_option :parallel, type: :numeric, desc: 'Number of parallel executions'
     method_option :dry_run, type: :boolean, desc: 'Show what would be done'
     method_option :debug, type: :boolean, desc: 'Show detailed command output (stdout/stderr)'
+    method_option :no_banner, type: :boolean, desc: 'Do not print banner'
+    method_option :format, type: :string, default: 'text', desc: 'Output format (text|json)'
+    method_option :retries, type: :numeric, desc: 'Retry count for network operations (default: 0)'
+    method_option :retry_delay, type: :numeric, desc: 'Retry delay seconds (default: 1)'
     def execute(task_file, task_name = nil)
       load_config_file
       show_banner_once
@@ -53,7 +58,10 @@ module Kdeploy
       load_task_file(task_file)
 
       tasks_to_run = determine_tasks(task_name)
-      execute_tasks(tasks_to_run)
+      all_results = execute_tasks(tasks_to_run)
+
+      # Exit non-zero if any executed host failed.
+      exit 1 if any_failed?(all_results)
     rescue StandardError => e
       puts Kdeploy::Banner.show_error(e.message)
       exit 1
@@ -189,6 +197,7 @@ module Kdeploy
     def show_banner_once
       @banner_printed ||= false
       return if @banner_printed
+      return if options[:no_banner]
 
       puts Kdeploy::Banner.show
       @banner_printed = true
@@ -208,7 +217,9 @@ module Kdeploy
       end
 
       # Show combined summary at the end for all tasks
-      print_all_tasks_summary(all_results) unless all_results.empty?
+      print_all_tasks_summary(all_results) unless all_results.empty? || options[:format] == 'json'
+
+      all_results
     end
 
     def execute_single_task(task)
@@ -221,7 +232,11 @@ module Kdeploy
       end
 
       if options[:dry_run]
-        print_dry_run(hosts, task)
+        if options[:format] == 'json'
+          print_dry_run_json(hosts, task)
+        else
+          print_dry_run(hosts, task)
+        end
         return nil
       end
 
@@ -232,20 +247,34 @@ module Kdeploy
       output = ConsoleOutput.new
       parallel_count = options[:parallel] || Configuration.default_parallel
       debug_mode = options[:debug] || false
+      retries = options[:retries].nil? ? Configuration.default_retries : options[:retries]
+      retry_delay = options[:retry_delay].nil? ? Configuration.default_retry_delay : options[:retry_delay]
       base_dir = @task_file_dir
       runner = Runner.new(
         hosts, self.class.kdeploy_tasks,
         parallel: parallel_count,
         output: output,
         debug: debug_mode,
-        base_dir: base_dir
+        base_dir: base_dir,
+        retries: retries,
+        retry_delay: retry_delay
       )
       results = runner.run(task)
-      # Don't show summary here - it will be shown at the end for all tasks
-      print_results(results, task, show_summary: false, debug: debug_mode)
+      if options[:format] == 'json'
+        print_results_json(task, results)
+      else
+        # Don't show summary here - it will be shown at the end for all tasks
+        print_results(results, task, show_summary: false, debug: debug_mode)
+      end
       results
     end
 
+    def any_failed?(all_results)
+      all_results.values.any? do |task_results|
+        task_results.values.any? { |result| result[:status] == :failed }
+      end
+    end
+
     def print_all_tasks_summary(all_results)
       debug_mode = options[:debug] || false
       formatter = OutputFormatter.new(debug: debug_mode)
@@ -272,6 +301,76 @@ module Kdeploy
       end
     end
 
+    def print_results_json(task_name, results)
+      payload = {
+        task: task_name.to_s,
+        results: results.transform_values { |r| serialize_host_result(r) }
+      }
+      puts JSON.generate(payload)
+    end
+
+    def print_dry_run_json(hosts, task_name)
+      tasks = self.class.kdeploy_tasks
+      commands = tasks[task_name][:block].call
+
+      payload = {
+        task: task_name.to_s,
+        dry_run: true,
+        planned: hosts.transform_values do |_config|
+          commands.map { |cmd| serialize_planned_step(cmd) }
+        end
+      }
+
+      puts JSON.generate(payload)
+    end
+
+    def serialize_host_result(result)
+      {
+        status: result[:status].to_s,
+        error: result[:error],
+        steps: Array(result[:output]).map { |step| serialize_step(step) }
+      }
+    end
+
+    def serialize_step(step)
+      out = {
+        type: step[:type].to_s,
+        command: step[:command],
+        duration: step[:duration]
+      }
+
+      out[:result] = step[:result] if step[:type] == :sync
+
+      if options[:debug] && step[:type] == :run && step[:output].is_a?(Hash)
+        out[:stdout] = step[:output][:stdout]
+        out[:stderr] = step[:output][:stderr]
+      end
+
+      out
+    end
+
+    def serialize_planned_step(cmd)
+      case cmd[:type]
+      when :run
+        { type: 'run', command: cmd[:command], sudo: cmd[:sudo] }
+      when :upload
+        { type: 'upload', source: cmd[:source], destination: cmd[:destination] }
+      when :upload_template
+        { type: 'upload_template', source: cmd[:source], destination: cmd[:destination], variables: cmd[:variables] }
+      when :sync
+        {
+          type: 'sync',
+          source: cmd[:source],
+          destination: cmd[:destination],
+          ignore: cmd[:ignore] || [],
+          exclude: cmd[:exclude] || [],
+          delete: cmd[:delete] || false
+        }
+      else
+        { type: cmd[:type].to_s }
+      end
+    end
+
     def extract_error_message(result)
       return result[:error] if result[:error]
 

data/lib/kdeploy/command_executor.rb

@@ -3,10 +3,12 @@
 module Kdeploy
   # Executes a single command and records execution time
   class CommandExecutor
-    def initialize(executor, output, debug: false)
+    def initialize(executor, output, debug: false, retries: 0, retry_delay: 1)
       @executor = executor
       @output = output
       @debug = debug
+      @retries = retries.to_i
+      @retry_delay = retry_delay.to_f
     end
 
     def execute_run(command, host_name)
@@ -18,21 +20,19 @@ module Kdeploy
       pastel = @output.respond_to?(:pastel) ? @output.pastel : Pastel.new
 
       result, duration = measure_time do
-        @executor.execute(cmd, use_sudo: use_sudo)
+        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
 
-      # Show command output only in debug mode
-      show_command_output(result) if @debug
       { 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]}")
       _result, duration = measure_time do
-        @executor.upload(command[:source], command[:destination])
+        with_retries { @executor.upload(command[:source], command[:destination]) }
       end
       {
         command: "upload: #{command[:source]} -> #{command[:destination]}",
@@ -44,7 +44,9 @@ module Kdeploy
     def execute_upload_template(command, host_name)
       show_command_header(host_name, :upload_template, "#{command[:source]} -> #{command[:destination]}")
       _result, duration = measure_time do
-        @executor.upload_template(command[:source], command[:destination], command[:variables])
+        with_retries do
+          @executor.upload_template(command[:source], command[:destination], command[:variables])
+        end
       end
       {
         command: "upload_template: #{command[:source]} -> #{command[:destination]}",
@@ -60,13 +62,15 @@ module Kdeploy
       show_command_header(host_name, :sync, description)
 
       result, duration = measure_time do
-        @executor.sync_directory(
-          source,
-          destination,
-          ignore: command[:ignore] || [],
-          exclude: command[:exclude] || [],
-          delete: command[:delete] || false
-        )
+        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)
@@ -99,27 +103,16 @@ module Kdeploy
       [result, duration]
     end
 
-    def show_command_output(output)
-      return unless output.is_a?(Hash)
+    def with_retries
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue SSHError, SCPError, TemplateError
+        raise if attempts > (@retries + 1)
 
-      pastel = @output.respond_to?(:pastel) ? @output.pastel : Pastel.new
-      show_stdout(output[:stdout])
-      show_stderr(output[:stderr], pastel)
-    end
-
-    def show_stdout(stdout)
-      return unless stdout && !stdout.empty?
-
-      stdout.each_line do |line|
-        @output.write_line("    #{line.rstrip}") unless line.strip.empty?
-      end
-    end
-
-    def show_stderr(stderr, pastel)
-      return unless stderr && !stderr.empty?
-
-      stderr.each_line do |line|
-        @output.write_line(pastel.green("    #{line.rstrip}")) unless line.strip.empty?
+        sleep(@retry_delay) if @retry_delay.positive?
+        retry
       end
     end
 

data/lib/kdeploy/configuration.rb

@@ -8,17 +8,23 @@ module Kdeploy
     DEFAULT_PARALLEL = 10
     DEFAULT_SSH_TIMEOUT = 30
     DEFAULT_VERIFY_HOST_KEY = :never
+    DEFAULT_RETRIES = 0
+    DEFAULT_RETRY_DELAY = 1
     CONFIG_FILE_NAME = '.kdeploy.yml'
 
     class << self
       attr_accessor :default_parallel,
                     :default_ssh_timeout,
-                    :default_verify_host_key
+                    :default_verify_host_key,
+                    :default_retries,
+                    :default_retry_delay
 
       def reset
         @default_parallel = DEFAULT_PARALLEL
         @default_ssh_timeout = DEFAULT_SSH_TIMEOUT
         @default_verify_host_key = DEFAULT_VERIFY_HOST_KEY
+        @default_retries = DEFAULT_RETRIES
+        @default_retry_delay = DEFAULT_RETRY_DELAY
       end
 
       def load_from_file(config_path = nil)
@@ -56,6 +62,8 @@ module Kdeploy
         @default_parallel = config['parallel'] if config.key?('parallel')
         @default_ssh_timeout = config['ssh_timeout'] if config.key?('ssh_timeout')
         @default_verify_host_key = parse_verify_host_key(config['verify_host_key']) if config.key?('verify_host_key')
+        @default_retries = config['retries'] if config.key?('retries')
+        @default_retry_delay = config['retry_delay'] if config.key?('retry_delay')
       end
 
       def parse_verify_host_key(value)

data/lib/kdeploy/dsl.rb

@@ -5,12 +5,33 @@ require 'set'
 module Kdeploy
   # Domain-specific language for defining hosts, roles, and tasks
   module DSL
+    def self.included(base)
+      # Support `include Kdeploy::DSL` by promoting the DSL methods to class methods.
+      # This keeps tests and external integrations simpler while preserving the
+      # primary usage pattern (CLI uses `extend DSL`).
+      base.extend(self)
+    end
+
     def self.extended(base)
       base.instance_variable_set(:@kdeploy_hosts, {})
       base.instance_variable_set(:@kdeploy_tasks, {})
       base.instance_variable_set(:@kdeploy_roles, {})
     end
 
+    # Stable read accessors for tests/integrations.
+    # Keep these as aliases so internal storage can evolve without breaking callers.
+    def hosts
+      kdeploy_hosts
+    end
+
+    def tasks
+      kdeploy_tasks
+    end
+
+    def roles
+      kdeploy_roles
+    end
+
     def kdeploy_hosts
       @kdeploy_hosts ||= {}
     end

data/lib/kdeploy/file_filter.rb

@@ -47,8 +47,14 @@ module Kdeploy
                   .gsub('[!', '[^')          # [^...] negation
                   .gsub('[', '[')            # Character class
 
-      # Anchor to start if pattern doesn't start with **
-      regex_str = "^#{regex_str}" unless pattern.start_with?('**')
+      # gitignore semantics: patterns without a slash match in any directory.
+      # e.g. "*.log" should match "a.log" and "logs/a.log".
+      if !pattern.include?('/') && !pattern.start_with?('**')
+        regex_str = "(?:^|.*/)#{regex_str}"
+      elsif !pattern.start_with?('**')
+        regex_str = "^#{regex_str}"
+      end
+
       # Match end of string or directory separator
       regex_str = "#{regex_str}(/|$)" unless pattern.end_with?('*') || pattern.end_with?('**')
 
@@ -64,8 +70,13 @@ module Kdeploy
     def relative_path_for(file_path, base_path)
       return file_path.to_s unless base_path
 
+      file = Pathname.new(file_path.to_s)
+
+      # If caller already passed a relative path (common in sync traversal),
+      # keep it as-is to avoid Pathname#relative_path_from prefix errors.
+      return file_path.to_s unless file.absolute?
+
       base = Pathname.new(base_path)
-      file = Pathname.new(file_path)
       file.relative_path_from(base).to_s
     end
   end

data/lib/kdeploy/help_formatter.rb

@@ -27,8 +27,13 @@ module Kdeploy
       <<~COMMANDS
         #{@pastel.bright_yellow('🚀')} #{@pastel.bright_white('execute TASK_FILE [TASK]')}     Execute deployment tasks from file
         #{@pastel.dim('    --limit HOSTS')}              Limit to specific hosts (comma-separated)
-        #{@pastel.dim('    --parallel NUM')}             Number of parallel executions (default: 5)
+        #{@pastel.dim('    --parallel NUM')}             Number of parallel executions (default: 10; overridden by .kdeploy.yml)
         #{@pastel.dim('    --dry-run')}                  Show what would be done without executing
+        #{@pastel.dim('    --debug')}                    Show detailed command output (stdout/stderr)
+        #{@pastel.dim('    --no-banner')}                Do not print banner (automation-friendly)
+        #{@pastel.dim('    --format FORMAT')}            Output format (text|json)
+        #{@pastel.dim('    --retries N')}                Retry count for network operations (default: 0; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --retry-delay SECONDS')}      Retry delay seconds (default: 1; overridden by .kdeploy.yml)
 
         #{@pastel.bright_yellow('🆕')} #{@pastel.bright_white('init [DIR]')}                  Initialize new deployment project
         #{@pastel.bright_yellow('ℹ️')} #{@pastel.bright_white('version')}                    Show version information
@@ -54,6 +59,12 @@ module Kdeploy
 
         #{@pastel.dim('# Preview deployment')}
         #{@pastel.bright_cyan('kdeploy execute deploy.rb deploy_web --dry-run')}
+
+        #{@pastel.dim('# Machine-readable output')}
+        #{@pastel.bright_cyan('kdeploy execute deploy.rb deploy_web --format json --no-banner')}
+
+        #{@pastel.dim('# Retry transient network failures')}
+        #{@pastel.bright_cyan('kdeploy execute deploy.rb deploy_web --retries 3 --retry-delay 1')}
       EXAMPLES
     end
 

data/lib/kdeploy/runner.rb

@@ -6,21 +6,23 @@ module Kdeploy
   # Concurrent task runner for executing tasks across multiple hosts
   class Runner
     def initialize(hosts, tasks, parallel: Configuration.default_parallel, output: ConsoleOutput.new,
-                   debug: false, base_dir: nil)
+                   debug: false, base_dir: nil, retries: Configuration.default_retries,
+                   retry_delay: Configuration.default_retry_delay)
       @hosts = hosts
       @tasks = tasks
       @parallel = parallel
       @output = output
       @debug = debug
       @base_dir = base_dir
+      @retries = retries
+      @retry_delay = retry_delay
       @pool = Concurrent::FixedThreadPool.new(@parallel)
       @results = Concurrent::Hash.new
     end
 
     def run(task_name)
       task = find_task(task_name)
-      results = execute_concurrent_tasks(task)
-      results
+      execute_concurrent_tasks(task, task_name)
     ensure
       @pool.shutdown
     end
@@ -33,8 +35,8 @@ module Kdeploy
       task
     end
 
-    def execute_concurrent_tasks(task)
-      futures = create_task_futures(task)
+    def execute_concurrent_tasks(task, task_name)
+      futures = create_task_futures(task, task_name)
 
       # If no hosts, return empty results immediately
       return @results if futures.empty?
@@ -97,47 +99,53 @@ module Kdeploy
       @results
     end
 
-    def create_task_futures(task)
+    def create_task_futures(task, task_name)
       # Store host names in order to match with futures
       @host_names = @hosts.keys
       @hosts.map do |name, config|
         Concurrent::Future.execute(executor: @pool) do
-          execute_task_for_host(name, config, task)
+          execute_task_for_host(name, config, task, task_name)
         end
       end
     end
 
     private
 
-    def execute_task_for_host(name, config, task)
+    def execute_task_for_host(name, config, task, task_name)
       # Add base_dir to config for path resolution
       config_with_base_dir = config.merge(base_dir: @base_dir)
       executor = Executor.new(config_with_base_dir)
-      command_executor = CommandExecutor.new(executor, @output, debug: @debug)
+      command_executor = CommandExecutor.new(
+        executor,
+        @output,
+        debug: @debug,
+        retries: @retries,
+        retry_delay: @retry_delay
+      )
       result = { status: :success, output: [] }
 
       begin
-        execute_grouped_commands(task, command_executor, name, result)
+        execute_grouped_commands(task, command_executor, name, result, task_name)
       rescue StandardError => e
         # Ensure result is always set, even on error
         # Don't re-raise, as it would cause future.value to fail
-        result = { status: :failed, error: e.message, output: [] }
+        result = { status: :failed, error: "#{e.class}: #{e.message}", output: [] }
       end
 
       # Return the result so it can be collected from the future
       [name, result]
     end
 
-    def execute_grouped_commands(task, command_executor, name, result)
+    def execute_grouped_commands(task, command_executor, name, result, task_name)
       commands = task[:block].call
       grouped_commands = CommandGrouper.group(commands)
 
       grouped_commands.each_value do |command_group|
-        execute_command_group(command_group, command_executor, name, result)
+        execute_command_group(command_group, command_executor, name, result, task_name)
       end
     end
 
-    def execute_command_group(command_group, command_executor, name, result)
+    def execute_command_group(command_group, command_executor, name, result, task_name)
       first_cmd = command_group.first
       task_desc = CommandGrouper.task_description(first_cmd)
       show_task_header(task_desc)
@@ -149,7 +157,7 @@ module Kdeploy
           @output.write_line(pastel.dim("    [Step #{index + 1}/#{command_group.length}]"))
         end
 
-        step_result = execute_command(command_executor, command, name)
+        step_result = execute_command_with_context(command_executor, command, name, task_name)
         result[:output] << step_result
       end
     end
@@ -169,6 +177,29 @@ module Kdeploy
       end
     end
 
+    def execute_command_with_context(command_executor, command, host_name, task_name)
+      execute_command(command_executor, command, host_name)
+    rescue StandardError => e
+      step = step_description(command)
+      raise StandardError, "task=#{task_name} host=#{host_name} step=#{step} error=#{e.class}: #{e.message}"
+    end
+
+    def step_description(command)
+      case command[:type]
+      when :run
+        first = command[:command].to_s.lines.first&.strip
+        "run: #{first}"
+      when :upload
+        "upload: #{command[:source]} -> #{command[:destination]}"
+      when :upload_template
+        "upload_template: #{command[:source]} -> #{command[:destination]}"
+      when :sync
+        "sync: #{command[:source]} -> #{command[:destination]}"
+      else
+        command[:type].to_s
+      end
+    end
+
     def show_task_header(task_desc)
       # Don't show command header during execution - it will be shown in results
       # This reduces noise during execution

data/lib/kdeploy/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kdeploy
 version: !ruby/object:Gem::Version
-  version: 1.2.30
+  version: 1.2.33
 platform: ruby
 authors:
 - Kk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-21 00:00:00.000000000 Z
+date: 2026-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt_pbkdf
@@ -160,6 +160,7 @@ extensions:
 - ext/mkrf_conf.rb
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - README.md
 - README_EN.md
 - exe/kdeploy
@@ -184,6 +185,7 @@ files:
 - lib/kdeploy/runner.rb
 - lib/kdeploy/template.rb
 - lib/kdeploy/version.rb
+- r.md
 homepage: https://github.com/kevin197011/kdeploy
 licenses:
 - MIT