kdeploy 1.2.30 → 1.2.38

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb0be08200c1be7fccc54f427d3dfc8111113bde76217642cb18a5a1d7bb6ea
-  data.tar.gz: 2002567662d65d4d6927e2090b56ce88e8acfb5d64eb758c4a5b92a06bf3be95
+  metadata.gz: 29a2ac38f02097f22a48646d3d6483b4e3fd65513f01eb6044ba7efd85f9e51f
+  data.tar.gz: 27d6af727a2929a8fe7ec7bca6e7b63a8b2acc6a373ab73baa89b536fbb76941
 SHA512:
-  metadata.gz: 2c9f208415d75f9edd4b06ec15f8ff25e730f2a2b0a8356b6d10a15db441a32a275544e8efc822edbeba28eebad3528093c2fff0baf15378a579fd508e2fe250
-  data.tar.gz: eea102b4f5628f869299258fbc775b5c95b1a3c8105cedb2dedd731915016c02714689f14015b105cf38fa39505d4e14c4aa8080fdbf36cd66760b3a1eaa685b
+  metadata.gz: 6ec34aac0c945e25101d9a3d91b68121660a5ab16d47cb7d8cb736805d83ef4f09fd92701351051449ecf6427f85f955a93384ef99cffebebeae09cf1b9a11e1
+  data.tar.gz: 416f3adfc65db0a5534cafc2853296fe585742470a482802ad08156f13acb1259ff86bf33c5a10c6c5d671eaae2b04b5a8de3c1f2bdfb0e82646a58bc3512cfd

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
 ```
@@ -515,6 +529,67 @@ sync "./config", "/etc/app",
 - 同步静态资源文件
 - 保持本地和远程目录结构一致
 
+### Chef 风格资源 DSL
+
+Kdeploy 提供类似 Chef 的声明式资源 DSL，可替代或与底层原语（`run`、`upload`、`upload_template`）混用。
+
+#### `package` - 安装系统包
+
+```ruby
+package "nginx"
+package "nginx", version: "1.18"
+package "nginx", platform: :yum  # CentOS/RHEL
+```
+
+默认使用 apt（Ubuntu/Debian）；`platform: :yum` 生成 yum 命令。
+
+#### `service` - 管理系统服务（systemd）
+
+```ruby
+service "nginx", action: [:enable, :start]
+service "nginx", action: :restart
+service "nginx", action: [:stop, :disable]
+```
+
+支持 `:start`、`:stop`、`:restart`、`:reload`、`:enable`、`:disable`。
+
+#### `template` - 部署 ERB 模板
+
+```ruby
+template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+# 或 block 语法
+template "/etc/app.conf" do
+  source "./config/app.erb"
+  variables(domain: "example.com")
+end
+```
+
+#### `file` - 上传本地文件
+
+```ruby
+file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+```
+
+#### `directory` - 确保远程目录存在
+
+```ruby
+directory "/etc/nginx/conf.d"
+directory "/var/log/app", mode: "0755"
+```
+
+**示例：使用资源 DSL 部署 Nginx**
+
+```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"
+  service "nginx", action: [:enable, :restart]
+end
+```
+
 ### 模板支持
 
 Kdeploy 支持 ERB（嵌入式 Ruby）模板，用于动态配置生成。
@@ -861,7 +936,6 @@ kdeploy execute deploy.rb deploy --parallel 3
 - **Executor** (`executor.rb`): SSH/SCP 执行引擎
 - **Runner** (`runner.rb`): 并发任务执行协调器
 - **CommandExecutor** (`command_executor.rb`): 单个命令执行
-- **CommandGrouper** (`command_grouper.rb`): 命令分组逻辑
 - **Template** (`template.rb`): ERB 模板渲染
 - **Output** (`output.rb`): 输出格式化和显示
 - **Configuration** (`configuration.rb`): 配置管理
@@ -871,10 +945,9 @@ kdeploy execute deploy.rb deploy --parallel 3
 
 1. **解析配置**: 加载并解析 `deploy.rb`
 2. **解析主机**: 根据任务定义确定目标主机
-3. **分组命令**: 按类型分组命令以提高执行效率
-4. **并发执行**: 跨主机并行运行任务
-5. **收集结果**: 收集执行结果和状态
-6. **显示输出**: 格式化并向用户显示结果
+3. **并发执行**: 跨主机并行运行任务，按序执行每台主机上的命令
+4. **收集结果**: 收集执行结果和状态
+5. **显示输出**: 格式化并向用户显示结果
 
 ### 并发模型
 
@@ -914,7 +987,6 @@ kdeploy/
 │       ├── executor.rb         # SSH/SCP 执行器
 │       ├── runner.rb           # 任务运行器
 │       ├── command_executor.rb # 命令执行器
-│       ├── command_grouper.rb  # 命令分组器
 │       ├── template.rb         # 模板处理器
 │       ├── output.rb           # 输出接口
 │       ├── configuration.rb    # 配置

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
 ```
@@ -472,6 +486,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"
+  service "nginx", action: [:enable, :restart]
+end
+```
+
 ### Template Support
 
 Kdeploy supports ERB (Embedded Ruby) templates for dynamic configuration generation.
@@ -869,7 +944,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
@@ -879,10 +953,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
 
@@ -922,7 +995,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

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
@@ -134,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
 
@@ -171,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)
@@ -189,6 +212,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
@@ -205,10 +229,15 @@ 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
-      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 +250,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 +265,40 @@ 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 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)
@@ -272,6 +325,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]