|
| 1 | +# Copilot Instructions for ruby-butler2 |
| 2 | + |
| 3 | +## Project Overview |
| 4 | +- **Language:** Rust (Cargo workspace with 2024 edition) |
| 5 | +- **Purpose:** A sophisticated Ruby environment manager (not version switcher) that orchestrates Ruby installations and gem collections with distinguished precision |
| 6 | +- **Inspiration:** Cargo, uv, and npm - environment-agnostic tools that transcend shell-based approaches |
| 7 | +- **Tone:** Gentleman's butler - refined, sophisticated, helpful, and elegant in all communications |
| 8 | + |
| 9 | +## Main Components |
| 10 | +- **`crates/rb-core/`**: Core library for Ruby/Gem environment detection and orchestration |
| 11 | + - `src/butler/`: Environment composition and orchestration (ButlerRuntime) |
| 12 | + - `src/ruby/`: Ruby runtime detection and abstraction (RubyRuntimeDetector) |
| 13 | + - `src/gems/`: RubyGems runtime management (GemRuntime) |
| 14 | + - `tests/`: Integration and unit tests with `RubySandbox` helpers |
| 15 | +- **`crates/rb-cli/`**: Distinguished command-line interface |
| 16 | + - `src/bin/rb.rs`: Main binary entry point |
| 17 | + - `src/commands/`: Modular command implementations (runtime, exec) |
| 18 | + - `src/lib.rs`: CLI types, argument parsing with refined help text |
| 19 | + - `tests/integration_tests.rs`: End-to-end CLI testing |
| 20 | +- **`crates/rb-tests/`**: Sophisticated testing utilities |
| 21 | + - `src/sandbox.rs`: `RubySandbox` for filesystem-based test setups |
| 22 | + |
| 23 | +## Architecture & Design Philosophy |
| 24 | +- **Environment Composition**: Each runtime implements `EnvProvider` trait to expose environment modifications (PATH, GEM_HOME, GEM_PATH) |
| 25 | +- **Ruby Discovery**: `RubyRuntimeDetector::discover()` scans directories for Ruby installations using semver sorting |
| 26 | +- **Butler Pattern**: `ButlerRuntime` aggregates all providers and composes the final environment for process execution |
| 27 | +- **Environment Agnostic**: No shell dependencies - works universally across Windows, macOS, and Linux |
| 28 | +- **Gentleman's Approach**: All user-facing text uses refined, sophisticated language befitting a distinguished developer |
| 29 | + |
| 30 | +## CLI Commands & User Interface |
| 31 | +- **`rb runtime` / `rb rt`**: Survey and present Ruby estate with elegant formatting |
| 32 | +- **`rb exec` / `rb x`**: Execute commands within meticulously prepared Ruby environments |
| 33 | +- **Help System**: Cargo/uv-inspired styling with gentleman's language throughout |
| 34 | +- **Error Messages**: Refined, helpful guidance rather than technical jargon |
| 35 | +- **Output Formatting**: Clean alignment, appropriate use of color, dignified presentation |
| 36 | + |
| 37 | +## Language & Tone Guidelines |
| 38 | +**Always maintain the gentleman's butler persona:** |
| 39 | +- Use refined vocabulary: "distinguished", "meticulously prepared", "with appropriate dignity" |
| 40 | +- Avoid technical jargon in user-facing messages |
| 41 | +- Present information with ceremony and proper formatting |
| 42 | +- Use "Ruby environment manager" never "version manager" |
| 43 | +- Error messages should be helpful and courteous: "Selection Failed" not "Error" |
| 44 | +- Success messages should be celebratory: "Environment Ready" with context |
| 45 | +- Refer to gem directories as "Gem home" (correct technical term) |
| 46 | +- Maintain consistency: "Installation", "Gem home", "Gem libraries", "Executable paths" |
| 47 | + |
| 48 | +## Developer Workflows |
| 49 | +- **Build**: `cargo build` (workspace root) or `cargo build --package <crate>` |
| 50 | +- **Test**: `cargo test` for all, `cargo test --package <crate>` for specific |
| 51 | +- **Debug**: Use `--show-output` for test debugging, `cargo run --bin rb -- <args>` for CLI testing |
| 52 | +- **Integration Tests**: Use `RubySandbox` for realistic filesystem-based testing |
| 53 | + |
| 54 | +## Project-Specific Patterns |
| 55 | +- **Environment Variables**: |
| 56 | + - `GEM_HOME` and `GEM_PATH` always set to same value (per chruby pattern) |
| 57 | + - PATH composition includes Ruby bin and gem bin directories |
| 58 | + - All environment composition through `ButlerRuntime::env_vars()` |
| 59 | +- **Testing Conventions**: |
| 60 | + - Integration tests use `RubySandbox` for filesystem simulation |
| 61 | + - Place test helpers in dedicated test crates (`rb-tests`) |
| 62 | + - Test both happy path and error conditions with proper assertions |
| 63 | +- **Code Style**: |
| 64 | + - Imports at top of files |
| 65 | + - Tests at end of files |
| 66 | + - Use descriptive variable names reflecting the gentleman's approach |
| 67 | + - Error handling with helpful context for users |
| 68 | + |
| 69 | +## Key Technical Details |
| 70 | +- **Ruby Detection**: Scans for `ruby-X.Y.Z` directories, validates with `bin/ruby` executable |
| 71 | +- **Gem Runtime**: Infers from Ruby version using standard gem directory patterns |
| 72 | +- **Environment Building**: Composes PATH, GEM_HOME, GEM_PATH for subprocess execution |
| 73 | +- **Version Handling**: Uses `semver` crate for proper version parsing and comparison |
| 74 | +- **Cross-Platform**: Handles Windows/Unix path separators and executable extensions |
| 75 | + |
| 76 | +## Integration Points |
| 77 | +- **No External Dependencies**: All logic is local and filesystem-based |
| 78 | +- **Ruby Ecosystem**: Compatible with standard Ruby installation patterns (ruby-install, etc.) |
| 79 | +- **Gem Management**: Works with bundler, gem commands, and standard RubyGems workflows |
| 80 | +- **Development Tools**: Integrates cleanly with cargo-style development workflows |
| 81 | + |
| 82 | +## Key Files & Responsibilities |
| 83 | +- `crates/rb-core/src/butler/mod.rs`: Main environment composition logic |
| 84 | +- `crates/rb-core/src/butler/env_provider.rs`: Environment modification trait |
| 85 | +- `crates/rb-core/src/ruby/detector.rs`: Ruby installation discovery |
| 86 | +- `crates/rb-core/src/gems/mod.rs`: Gem environment management |
| 87 | +- `crates/rb-cli/src/lib.rs`: CLI argument parsing and help text |
| 88 | +- `crates/rb-cli/src/commands/runtime.rs`: Ruby estate surveying and presentation |
| 89 | +- `crates/rb-cli/src/commands/exec.rs`: Command execution in composed environments |
| 90 | +- `crates/rb-tests/src/sandbox.rs`: Test environment simulation |
| 91 | + |
| 92 | +## Quality Standards |
| 93 | +- **All tests must pass**: Unit tests, integration tests, and end-to-end CLI tests |
| 94 | +- **Consistent messaging**: All user-facing text follows gentleman's butler tone |
| 95 | +- **Clean formatting**: Perfect text alignment, appropriate use of color and styling |
| 96 | +- **Cross-platform compatibility**: Windows, macOS, and Linux support |
| 97 | +- **Error resilience**: Graceful handling of missing directories, invalid versions, etc. |
0 commit comments