{"id":31757695,"url":"https://github.com/iepathos/rustle-plan","last_synced_at":"2025-10-09T20:01:55.001Z","repository":{"id":304110493,"uuid":"1017736798","full_name":"iepathos/rustle-plan","owner":"iepathos","description":"A specialized execution planner for the Rustle automation ecosystem that generates optimized execution plans with binary deployment strategies.","archived":false,"fork":false,"pushed_at":"2025-07-11T05:47:06.000Z","size":126,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-11T09:25:09.629Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iepathos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T02:55:58.000Z","updated_at":"2025-07-11T05:47:09.000Z","dependencies_parsed_at":"2025-07-11T09:31:22.231Z","dependency_job_id":"82f86d34-96e3-492a-8d39-92bbbf850d59","html_url":"https://github.com/iepathos/rustle-plan","commit_stats":null,"previous_names":["iepathos/rustle-plan"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/iepathos/rustle-plan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iepathos%2Frustle-plan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iepathos%2Frustle-plan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iepathos%2Frustle-plan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iepathos%2Frustle-plan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iepathos","download_url":"https://codeload.github.com/iepathos/rustle-plan/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iepathos%2Frustle-plan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002006,"owners_count":26083258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T20:01:09.457Z","updated_at":"2025-10-09T20:01:54.995Z","avatar_url":"https://github.com/iepathos.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rustle-plan\n\n[![CI](https://github.com/iepathos/rustle-plan/actions/workflows/ci.yml/badge.svg)](https://github.com/iepathos/rustle-plan/actions/workflows/ci.yml)\n[![Security](https://github.com/iepathos/rustle-plan/actions/workflows/security.yml/badge.svg)](https://github.com/iepathos/rustle-plan/actions/workflows/security.yml)\n[![Release](https://github.com/iepathos/rustle-plan/actions/workflows/release.yml/badge.svg)](https://github.com/iepathos/rustle-plan/actions/workflows/release.yml)\n\nA specialized execution planner for the Rustle automation ecosystem that generates optimized execution plans with binary deployment strategies. This tool takes parsed playbooks from `rustle-parse` and produces detailed execution plans that optimize for minimal network overhead through intelligent parallelization and binary deployment planning.\n\n## 🚀 Features\n\n- **Optimized execution planning** from parsed playbooks with dependency analysis\n- **Binary deployment strategies** to minimize network round-trips and maximize performance\n- **Intelligent parallelization** with automatic detection of parallel execution opportunities\n- **Multiple execution strategies** including linear, rolling, free, and binary-hybrid modes\n- **Comprehensive dependency analysis** with circular dependency detection\n- **Execution time estimation** including binary compilation overhead\n- **Host filtering and task selection** with tag-based filtering support\n- **Execution graph visualization** for dependency analysis and optimization verification\n\n## 📦 Installation\n\n### From Source\n\n```bash\ngit clone \u003crepository-url\u003e rustle-plan\ncd rustle-plan\ncargo build --release\n```\n\nThe binary will be available at `target/release/rustle-plan`.\n\n### Development Setup\n\n```bash\n# Install development dependencies\nrustup component add rustfmt clippy\ncargo install cargo-watch cargo-tarpaulin cargo-audit\n\n# Run in development mode\ncargo run -- --help\n```\n\n## 🛠️ Usage\n\n### Basic Usage\n\n```bash\n# Generate execution plan from parsed playbook\nrustle-plan parsed_playbook.json\n\n# Plan from rustle-parse output (includes embedded inventory)\nrustle-plan rustle_parse_output.json\n\n# Use binary-hybrid strategy for optimal performance\nrustle-plan --strategy binary-hybrid --optimize parsed_playbook.json\n\n# Pipeline with rustle-parse\nrustle-parse playbook.yml | rustle-plan --strategy rolling\n```\n\n### Planning Options\n\n```bash\n# Host and task filtering\nrustle-plan --limit \"web*\" --tags \"deploy,config\" parsed_playbook.json\n\n# Execution strategies\nrustle-plan --strategy linear parsed_playbook.json        # Sequential execution\nrustle-plan --strategy rolling --serial 5 parsed_playbook.json  # Rolling updates\nrustle-plan --strategy free parsed_playbook.json          # Maximum parallelization\nrustle-plan --strategy binary-hybrid parsed_playbook.json # Optimal binary deployment\n\n# Binary deployment control\nrustle-plan --force-binary parsed_playbook.json          # Force binary for all suitable tasks\nrustle-plan --force-ssh parsed_playbook.json             # Disable binary deployment\nrustle-plan --binary-threshold 3 parsed_playbook.json    # Custom threshold for binary grouping\n```\n\n### Analysis and Inspection\n\n```bash\n# List planned tasks and execution order\nrustle-plan --list-tasks parsed_playbook.json\n\n# List target hosts\nrustle-plan --list-hosts parsed_playbook.json\n\n# Show planned binary deployments\nrustle-plan --list-binaries parsed_playbook.json\n\n# Generate dependency graph visualization\nrustle-plan --visualize -o dot parsed_playbook.json \u003e execution_graph.dot\n\n# Dry run with time estimates\nrustle-plan --dry-run --estimate-time parsed_playbook.json\n```\n\n### Performance Optimization\n\n```bash\n# Enable all optimizations\nrustle-plan --optimize --strategy binary-hybrid parsed_playbook.json\n\n# Custom parallelism settings\nrustle-plan --forks 100 --serial 10 parsed_playbook.json\n\n# Check mode planning (no changes)\nrustle-plan --check --diff parsed_playbook.json\n```\n\n## 📋 Command Line Reference\n\n```\nrustle-plan [OPTIONS] [PARSED_PLAYBOOK]\n\nArguments:\n  [PARSED_PLAYBOOK]  Path to parsed playbook file (or stdin if -)\n\nOptions:\n  -l, --limit \u003cPATTERN\u003e             Limit execution to specific hosts\n  -t, --tags \u003cTAGS\u003e                 Only run tasks with these tags\n      --skip-tags \u003cTAGS\u003e            Skip tasks with these tags\n  -s, --strategy \u003cSTRATEGY\u003e         Execution strategy [default: binary-hybrid]\n      --serial \u003cNUM\u003e                Number of hosts to run at once\n      --forks \u003cNUM\u003e                 Maximum parallel processes [default: 50]\n  -c, --check                       Check mode (don't make changes)\n      --diff                        Show file differences\n      --binary-threshold \u003cNUM\u003e      Minimum tasks for binary compilation [default: 5]\n      --force-binary                Force binary deployment for all suitable tasks\n      --force-ssh                   Force SSH execution (disable binary deployment)\n      --list-tasks                  List all planned tasks\n      --list-hosts                  List all target hosts\n      --list-binaries               List planned binary deployments\n      --visualize                   Generate execution graph visualization\n  -o, --output \u003cFORMAT\u003e             Output format [default: json]\n      --optimize                    Enable execution optimizations\n      --estimate-time               Include execution time estimates\n      --dry-run                     Plan but don't output execution plan\n  -v, --verbose                     Enable verbose output\n  -h, --help                        Print help\n  -V, --version                     Print version\n\nExecution Strategies:\n  linear         Sequential execution across all hosts\n  rolling        Rolling updates with configurable batch sizes\n  free           Maximum parallelization within dependency constraints\n  host-pinned    Pin tasks to specific hosts for locality\n  binary-hybrid  Intelligent mix of binary deployment and SSH execution\n  binary-only    Force binary deployment where possible\n\nOutput Formats:\n  json           Structured JSON execution plan (default)\n  binary         Compact binary format for efficient storage\n  dot            Graphviz DOT format for visualization\n```\n\n## 📁 Input Format\n\n`rustle-plan` expects JSON input from `rustle-parse` that includes both playbook and inventory data. The input format includes:\n\n```json\n{\n  \"metadata\": {\n    \"file_path\": \"example_playbook.yml\",\n    \"version\": null,\n    \"created_at\": \"2025-07-11T01:15:00.000000Z\",\n    \"checksum\": \"d48e92ff5b2b8cd603041d0d6a56a9c4674696e8e3c7601a6c526e6a37adea50\"\n  },\n  \"plays\": [\n    {\n      \"name\": \"Configure web servers\",\n      \"hosts\": [\"all\"],\n      \"tasks\": [\n        {\n          \"id\": \"task-1\",\n          \"name\": \"Install nginx\",\n          \"module\": \"package\",\n          \"args\": {\n            \"name\": \"nginx\",\n            \"state\": \"present\"\n          },\n          \"dependencies\": [],\n          \"tags\": [\"install\"],\n          \"when\": null,\n          \"notify\": [\"restart nginx\"]\n        }\n      ],\n      \"handlers\": [\n        {\n          \"id\": \"handler-1\",\n          \"name\": \"restart nginx\",\n          \"module\": \"service\",\n          \"args\": {\n            \"name\": \"nginx\",\n            \"state\": \"restarted\"\n          },\n          \"when\": null\n        }\n      ],\n      \"vars\": {}\n    }\n  ],\n  \"variables\": {},\n  \"inventory\": {\n    \"hosts\": [\"server1\", \"server2\", \"server3\"],\n    \"groups\": {\n      \"webservers\": [\"server1\", \"server2\"],\n      \"databases\": [\"server3\"]\n    },\n    \"vars\": {\n      \"nginx_version\": \"1.20.2\"\n    }\n  },\n  \"facts_required\": false,\n  \"vault_ids\": []\n}\n```\n\n## 📊 Output Format\n\nThe tool outputs detailed execution plans in JSON format by default:\n\n```json\n{\n  \"metadata\": {\n    \"created_at\": \"2025-07-11T01:08:23.589337Z\",\n    \"rustle_plan_version\": \"0.1.0\",\n    \"playbook_hash\": \"785bab203c116d67dcacce745579fcbd\",\n    \"inventory_hash\": \"653a2ee28be80c8e41d5251b3923d10d\",\n    \"planning_options\": {\n      \"strategy\": \"BinaryHybrid\",\n      \"forks\": 50,\n      \"binary_threshold\": 5\n    }\n  },\n  \"plays\": [\n    {\n      \"play_id\": \"play-0\",\n      \"name\": \"Configure web servers\",\n      \"strategy\": \"BinaryHybrid\",\n      \"hosts\": [\"localhost\"],\n      \"batches\": [\n        {\n          \"batch_id\": \"binary-batch\",\n          \"hosts\": [\"localhost\"],\n          \"tasks\": [\n            {\n              \"task_id\": \"task-1\",\n              \"name\": \"Install nginx\",\n              \"module\": \"package\",\n              \"execution_order\": 0,\n              \"can_run_parallel\": false,\n              \"estimated_duration\": {\"secs\": 66, \"nanos\": 0},\n              \"risk_level\": \"High\"\n            }\n          ],\n          \"parallel_groups\": []\n        }\n      ]\n    }\n  ],\n  \"binary_deployments\": [],\n  \"total_tasks\": 3,\n  \"estimated_duration\": {\"secs\": 31, \"nanos\": 960000000},\n  \"parallelism_score\": 0.33333334,\n  \"network_efficiency_score\": 0.2\n}\n```\n\n## 🔍 Planning Features\n\n### Dependency Analysis\n- **Explicit dependencies**: Respects task dependencies specified in playbooks\n- **Implicit dependencies**: Detects file-based and service-package dependencies\n- **Circular dependency detection**: Prevents invalid execution plans\n- **Cross-play dependencies**: Handles dependencies between different plays\n\n### Binary Deployment Optimization\n- **Task grouping**: Groups compatible tasks for binary deployment\n- **Compilation planning**: Determines when binary compilation is beneficial\n- **Network optimization**: Reduces SSH round-trips through binary execution\n- **Module compatibility**: Analyzes which modules can be statically linked\n\n### Parallelization Analysis\n- **Parallel group detection**: Identifies tasks that can run simultaneously\n- **Resource contention**: Prevents conflicts between parallel tasks\n- **Host-based parallelization**: Optimizes execution across multiple hosts\n- **Execution order optimization**: Minimizes overall execution time\n\n### Execution Strategies\n\n#### Linear Strategy\n- Sequential execution across all hosts\n- Minimal parallelization for maximum safety\n- Best for sensitive operations and debugging\n\n#### Rolling Strategy\n- Batch-based execution with configurable batch sizes\n- Ideal for zero-downtime deployments\n- Configurable failure thresholds\n\n#### Free Strategy\n- Maximum parallelization within dependency constraints\n- Optimal for performance when safety allows\n- Advanced resource management\n\n#### Binary-Hybrid Strategy\n- Intelligent mix of binary deployment and SSH execution\n- Automatic binary vs SSH decision making\n- Optimal balance of performance and compatibility\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ncargo test\n\n# Run tests with output\ncargo test -- --nocapture\n\n# Run integration tests only\ncargo test --test integration_tests\n\n# Generate code coverage\ncargo tarpaulin --out Html\n```\n\n### Test with Example Data\n\n```bash\n# Test with example playbook\ncargo run -- example_playbook.json --list-tasks\n\n# Test pipeline integration\necho '{\"name\":\"test\",\"plays\":[],\"vars\":{}}' | cargo run -- --dry-run\n\n# Test different strategies\ncargo run -- example_playbook.json --strategy rolling --serial 2\n```\n\n## 🔧 Development\n\n### Project Structure\n\n```\nrustle-plan/\n├── src/\n│   ├── bin/\n│   │   └── rustle-plan.rs        # CLI binary entry point\n│   ├── planner/\n│   │   ├── mod.rs                # Planner module exports\n│   │   ├── execution_plan.rs     # Core planning logic\n│   │   ├── binary_deployment.rs  # Binary deployment planning\n│   │   ├── dependency.rs         # Dependency analysis\n│   │   ├── optimization.rs       # Execution optimization\n│   │   ├── strategy.rs           # Execution strategies\n│   │   ├── condition.rs          # Conditional execution\n│   │   ├── estimation.rs         # Time estimation\n│   │   ├── validation.rs         # Plan validation\n│   │   ├── graph.rs              # Dependency graphs\n│   │   ├── suitability.rs        # Binary suitability analysis\n│   │   └── error.rs              # Error types\n│   ├── types/\n│   │   ├── mod.rs                # Type exports\n│   │   ├── plan.rs               # Plan data structures\n│   │   └── strategy.rs           # Strategy definitions\n│   └── lib.rs                    # Library exports\n├── tests/\n│   ├── integration_tests.rs      # Integration test suite\n│   └── planner/                  # Unit tests for planner modules\n├── specs/                        # Specification documents\n├── example_playbook.json         # Example input for testing\n├── Cargo.toml                    # Project manifest\n└── README.md                     # This file\n```\n\n### Key Dependencies\n\n- **serde** \u0026 **serde_json** - JSON serialization and parsing\n- **clap** - Command-line argument parsing\n- **petgraph** - Dependency graph analysis\n- **anyhow** \u0026 **thiserror** - Error handling\n- **tracing** - Structured logging\n- **chrono** - Date and time handling\n- **uuid** - Unique identifier generation\n\n## 🎯 Roadmap\n\n### Current Status ✅\n\n- [x] Basic execution plan generation\n- [x] Dependency analysis with cycle detection\n- [x] Multiple execution strategies\n- [x] Binary deployment planning framework\n- [x] CLI interface with comprehensive options\n- [x] JSON input/output support\n- [x] Integration with rustle-parse\n- [x] Execution time estimation\n- [x] Parallelization analysis\n\n### Near Term 🔄\n\n- [ ] Advanced binary deployment optimization\n- [ ] Rolling update strategy improvements\n- [ ] Enhanced visualization output\n- [ ] Performance benchmarking suite\n- [ ] Configuration file support\n\n### Future Enhancements 🔮\n\n- [ ] Real-time plan adaptation\n- [ ] Machine learning optimization\n- [ ] Advanced resource modeling\n- [ ] Integration with monitoring systems\n- [ ] Cloud-native execution strategies\n\n## 🤝 Integration with Rustle Ecosystem\n\n`rustle-plan` is designed to work seamlessly with other Rustle tools:\n\n```bash\n# Complete pipeline example\nrustle-parse playbook.yml \\\n  | rustle-plan --strategy binary-hybrid --optimize \\\n  | rustle-deploy \\\n  | rustle-exec\n```\n\n### Input Compatibility\n- **rustle-parse**: Consumes combined JSON output from rustle-parse including embedded inventory data\n\n### Output Integration\n- **rustle-deploy**: Execution plans used by rustle-deploy for binary compilation\n- **rustle-exec**: Plans consumed by rustle-exec for execution\n- **Monitoring**: Plan metadata for execution monitoring and analytics\n\n## 📄 Specifications\n\nThis implementation follows [Specification 010: Rustle Plan Tool](specs/010-rustle-plan.md). See the specs directory for detailed requirements and design decisions.\n\n## 🤝 Contributing\n\n1. Follow the guidelines in `CLAUDE.md`\n2. Ensure all tests pass: `cargo test`\n3. Run formatters: `cargo fmt`\n4. Check lints: `cargo clippy`\n5. Update documentation as needed\n\n## 📝 License\n\nGPL-3.0 License - see [LICENSE](LICENSE) file for details.\n\n---\n\nBuilt with ❤️ in Rust for high-performance automation planning.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiepathos%2Frustle-plan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiepathos%2Frustle-plan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiepathos%2Frustle-plan/lists"}