Development Setup

Prerequisites

Rust 1.90+ (nightly recommended)
Git
Make (optional but recommended)

Getting Started

Clone the repository

git clone https://github.com/WalshyDev/orb.git
cd orb

Build the project
Terminal window
```
make build
# or
cargo build
```
Run the tests
Terminal window
```
make test
# or
cargo test
```
Run orb locally
Terminal window
```
./target/debug/orb --help
```

Project Structure

orb/
├── packages/
│   ├── orb-cli/        # CLI application
│   │   ├── src/
│   │   └── tests/
│   ├── orb-client/     # HTTP client library
│   │   └── src/
│   └── orb-mockhttp/   # Mock HTTP server
│       ├── src/
│       └── tests/
├── Cargo.toml          # Workspace config
├── Makefile            # Build automation
└── README.md

Build Commands

# Debug build
make build

# Release build
make release

# Run tests
make test

# Generate coverage report
make coverage

# Lint check
make lint

# Auto-fix lint issues
make fix

# Clean build artifacts
make clean

# Show binary size
make size

Running Tests

# All tests
cargo test

# Specific package
cargo test -p orb-cli
cargo test -p orb-client
cargo test -p orb-mockhttp

# Specific test
cargo test test_name

# With output
cargo test -- --nocapture

Code Coverage

make coverage

Opens an HTML coverage report in your browser.

Development Workflow

Making Changes

Create a feature branch
Terminal window
```
git checkout -b feature/my-feature
```
Make your changes
Run tests
Terminal window
```
make test
```
Run lints
Terminal window
```
make lint
```
Commit your changes
Terminal window
```
git commit -m "Add my feature"
```

Adding a New CLI Option

Add the option to packages/orb-cli/src/cli.rs
Add validation (if needed) in cli.rs
Call validation from main.rs
Implement the feature in appropriate module
Add tests to packages/orb-cli/tests/options.rs

Adding Tests

Use test_case for parameterized tests:

use test_case::test_case;

#[test_case("input1", "expected1"; "test name 1")]
#[test_case("input2", "expected2"; "test name 2")]
fn test_feature(input: &str, expected: &str) {
    // Test implementation
}

For HTTP tests, use orb-mockhttp:

use orb_mockhttp::TestServerBuilder;

#[tokio::test]
async fn test_http_feature() {
    let server = TestServerBuilder::new().build();

    server.on_request("/test")
        .respond_with(200, "OK");

    // Test against server.url("/test")
}

Code Style

Use rustfmt for formatting (make fix)
Follow existing patterns in the codebase
Write helpful error messages
Use the fatal! macro only in CLI layer
Document public APIs with doc comments

Testing Guidelines

Use test_case for variations of the same test
Use orb-mockhttp for HTTP integration tests
Test error cases as well as success cases
Test edge cases (empty inputs, special characters, etc.)

Debugging

Verbose Output

# See request/response details
./target/debug/orb -v https://example.com

Test Output

# Show stdout during tests
cargo test -- --nocapture

Debug Build

# Full debug symbols
RUST_BACKTRACE=1 ./target/debug/orb https://example.com

Cross-Platform Building

# macOS Universal Binary
make build-macos

# Linux
make build-linux

# Windows
make build-windows

# All platforms
make build-binaries