feat: Batch Script Mode for Automated Workflows

[inureyes]

Overview

Implement a comprehensive Batch Script Mode that allows users to execute complex, multi-step operations across cluster nodes using script files. This feature will enable automated workflows, conditional execution, error handling, and sophisticated orchestration patterns while maintaining bssh's focus on parallel execution and simplicity.

Technical Approach

The implementation will follow a dual-format approach, supporting both YAML-based declarative scripts and a custom DSL for more dynamic operations. The script engine will leverage the existing executor infrastructure while adding new capabilities for state management, conditional logic, and error recovery.

Architecture Design

• Script Parser Layer: Flexible parser supporting both YAML and custom DSL formats
• Execution Engine: State-aware runtime with support for variables, conditions, and loops
• Integration Layer: Seamless integration with existing commands (exec, upload, download, ping)
• Session Manager: Persistent connection management for script execution
• Result Aggregator: Intelligent result collection with support for conditional branching

Why This Approach

1. Dual Format Support: YAML for simple declarative scripts, DSL for complex logic
2. Leverages Existing Infrastructure: Reuses executor, SSH client, and command modules
3. Progressive Enhancement: Simple scripts work immediately, advanced features are optional
4. Maintainability: Clear separation between parsing, execution, and state management
5. Performance: Connection reuse within script execution for efficiency
6. Security: Sandboxed execution with explicit variable scoping

Implementation Phases

Phase 1: Core Infrastructure

• Create script module structure at src/script/
• Implement YAML script parser (src/script/yaml_parser.rs)
• Design script data structures (src/script/types.rs)
• Implement script validator (src/script/validator.rs)

Phase 2: Execution Engine

• Build core execution engine (src/script/engine.rs)
• Implement state management (src/script/state.rs)
• Add error handling and recovery (src/script/error_handler.rs)
• Create execution context manager (src/script/context.rs)

Phase 3: Advanced Features

• Implement conditional execution (src/script/conditions.rs)
• Add loop support (src/script/loops.rs)
• Build template engine (src/script/template.rs)
• Implement built-in functions (src/script/functions.rs)

Phase 4: Custom DSL Implementation

• Design DSL syntax and grammar
• Implement DSL lexer (src/script/dsl/lexer.rs)
• Build DSL parser (src/script/dsl/parser.rs)
• Create DSL to internal representation converter (src/script/dsl/converter.rs)

Phase 5: Integration and CLI

• Add batch subcommand to CLI (src/cli.rs)
• Integrate with existing executor (src/executor.rs)
• Implement script output management
• Add interactive script debugger

Phase 6: Security and Performance

• Implement security controls (src/script/security.rs)
• Add performance optimizations
• Build script repository support

Phase 7: Testing and Documentation

• Write comprehensive unit tests
• Create integration tests
• Develop example scripts
• Write user documentation

Example Script Formats

YAML Format Example

name: System Update Script
version: 1.0
description: Update and restart services across cluster

variables:
  service_name: nginx
  backup_dir: /tmp/backups
  
defaults:
  on_error: continue
  timeout: 300
  parallel: 5

steps:
  - name: Create backup directory
    command: mkdir -p {{ backup_dir }}
    
  - name: Check service status
    command: systemctl status {{ service_name }}
    register: service_status
    ignore_errors: true
    
  - name: Stop service if running
    command: systemctl stop {{ service_name }}
    when: service_status.exit_code == 0
    
  - name: Update packages
    command: |
      apt-get update
      apt-get upgrade -y {{ service_name }}
    become: true

Custom DSL Format Example

script "System Update" {
    var service = "nginx"
    var backup_dir = "/tmp/backups"
    
    defaults {
        on_error = continue
        timeout = 5m
        parallel = 5
    }
    
    // Create backup directory on all nodes
    exec "mkdir -p ${backup_dir}"
    
    // Check service status and store result
    status = exec "systemctl status ${service}" {
        ignore_errors = true
    }
    
    // Conditional execution based on status
    if (status.success) {
        exec "systemctl stop ${service}"
    }
    
    // Update packages with retry logic
    retry(3, delay: 10s) {
        exec """
            apt-get update
            apt-get upgrade -y ${service}
        """ with sudo
    }
}

Dependencies

• serde_yaml - Already present for YAML parsing
• pest or nom - For DSL parsing (new dependency)
• handlebars or tera - For template engine (optional, could build custom)
• Existing bssh infrastructure (executor, SSH client, config management)

Success Criteria

• Successfully parse and execute YAML-based scripts with basic flow control
• Support for variables, conditions, and loops in both formats
• Error handling with configurable strategies (fail-fast, continue, retry)
• Performance: Minimal overhead compared to direct command execution
• Security: Sandboxed execution with no arbitrary code execution
• Compatibility: All existing bssh commands work within scripts
• Usability: Clear error messages and debugging capabilities
• Documentation: Comprehensive guides with real-world examples

Use Cases

• System updates across clusters
• Log collection and aggregation
• Rolling deployment patterns
• Health check and monitoring
• Backup and restore operations

Related Work

• Original task document: .claude/tasks/todo/2_batch_script_mode.md