sf-cli-wrapper/README.md

# Salesforce CLI Wrapper Scripts

A collection of convenient wrapper scripts for common Salesforce CLI operations. These scripts simplify complex `sf` commands by providing intuitive interfaces for deployment, testing, and org management tasks.

**Available for both Unix/Linux/macOS (Bash) and Windows (PowerShell).**

## Overview

This toolkit provides four main utilities:

- **`sf-deploy`** - Streamlined wrapper for `sf project deploy start`
- **`sf-dry-run`** - Validation wrapper for `sf project deploy start --dry-run`
- **`sf-web-open`** - Quick org browser opener for `sf org open`
- **`sf-check`** - Environment verification tool to check SF CLI installation and configuration

## Installation

### Unix/Linux/macOS (Bash)

1. Clone or download this repository to your preferred tools directory
2. Make the scripts executable:
   ```bash
   chmod +x sf-deploy sf-dry-run sf-web-open sf-check
   ```
3. Add the directory to your PATH or create symlinks in a directory that's already in your PATH:
   ```bash
   # Option 1: Add to PATH (add to your ~/.zshrc or ~/.bashrc)
   export PATH="$PATH:/path/to/sf-cli-wrapper"
   
   # Option 2: Create symlinks
   ln -s /path/to/sf-cli-wrapper/sf-deploy /usr/local/bin/sf-deploy
   ln -s /path/to/sf-cli-wrapper/sf-dry-run /usr/local/bin/sf-dry-run
   ln -s /path/to/sf-cli-wrapper/sf-web-open /usr/local/bin/sf-web-open
   ln -s /path/to/sf-cli-wrapper/sf-check /usr/local/bin/sf-check
   ```

### Windows (PowerShell)

1. Clone or download this repository to your preferred tools directory
2. Set the PowerShell execution policy to allow script execution (run as Administrator):
   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
   ```
3. Add the directory to your PATH or create a PowerShell profile with aliases:
   ```powershell
   # Option 1: Add to PATH (System Environment Variables)
   # Add C:\path\to\sf-cli-wrapper to your system PATH
   
   # Option 2: Create PowerShell aliases (add to your $PROFILE)
   Set-Alias sf-deploy "C:\path\to\sf-cli-wrapper\sf-deploy.ps1"
   Set-Alias sf-dry-run "C:\path\to\sf-cli-wrapper\sf-dry-run.ps1"
   Set-Alias sf-web-open "C:\path\to\sf-cli-wrapper\sf-web-open.ps1"
   Set-Alias sf-check "C:\path\to\sf-cli-wrapper\sf-check.ps1"
   ```

## Scripts

### sf-deploy

Wrapper for `sf project deploy start` that simplifies deploying multiple source files with optional test execution.

**Usage:**
```bash
sf-deploy -o <ORG_ALIAS_OR_USERNAME> (-s "<src1>,<src2>[,...]" | -d <DIRECTORY>) [-t "<Test1>,<Test2>[,...]"]
```

**Options:**
- `-o` - Org alias or username for --target-org
- `-s` - Comma-separated list of --source-dir paths
- `-d` - Single directory path to deploy (alternative to -s)
- `-t` - Comma-separated list of --tests (enables --test-level RunSpecifiedTests)
- `-h` - Show help

**Examples:**
```bash
# Deploy multiple flexipages (specific files)
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Page_Backup_With_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Deploy entire directory
sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"

# Deploy with specific tests
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" \
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"
```

### sf-dry-run

Wrapper for `sf project deploy start --dry-run` that validates deployments without actually deploying.

**Usage:**
```bash
sf-dry-run -o <ORG_ALIAS_OR_USERNAME> (-s "<src1>,<src2>[,...]" | -d <DIRECTORY>) [-t "<Test1>,<Test2>[,...]"]
```

**Options:**
- `-o` - Org alias or username for --target-org
- `-s` - Comma-separated list of --source-dir paths
- `-d` - Single directory path to validate (alternative to -s)
- `-t` - Comma-separated list of --tests (enables --test-level RunSpecifiedTests)
- `-h` - Show help

**Examples:**
```bash
# Validate multiple flexipages (specific files)
sf-dry-run -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Validate entire directory
sf-dry-run -o DEMO-ORG -d "force-app/main/default/classes"

# Validate with specific tests
sf-dry-run -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" \
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"
```

### sf-web-open

Wrapper for `sf org open` that provides quick access to Salesforce orgs with optional path navigation.

**Usage:**
```bash
sf-web-open [-o <ORG_ALIAS_OR_USERNAME>] [-p <RELATIVE_PATH>] [-U]
```

**Options:**
- `-o` - Org alias or username to pass as --target-org
- `-p` - Relative path to open inside the org (e.g., "/lightning/setup/SetupOneHome/home")
- `-U` - URL-only: print the URL instead of opening a browser (passes --url-only)
- `-h` - Show help

**Examples:**
```bash
# Open a specific org (default home)
sf-web-open -o DEMO-ORG

# Open Setup Home of a target org
sf-web-open -o NUSHUB-DR2 -p "/lightning/setup/SetupOneHome/home"

# Get just the URL for scripting
sf-web-open -o NUSHUB-DR2 -U

# Open the current default org
sf-web-open
```

### sf-check

Environment verification tool that checks if the Salesforce CLI is properly installed and configured.

**Usage:**
```bash
sf-check [-v] [-h]
```

**Options:**
- `-v` - Verbose output (show detailed information)
- `-h` - Show help

**Examples:**
```bash
# Basic environment check
sf-check

# Verbose output with detailed system information
sf-check -v
```

**What it checks:**
- SF CLI installation and version
- Authenticated orgs and default org configuration
- System requirements (Node.js, Git, etc.)
- SF CLI plugins and diagnostics
- Common configuration issues

## Automatic Environment Verification

All wrapper scripts (`sf-deploy`, `sf-dry-run`, `sf-web-open`) include built-in environment verification:

### ✅ **When SF CLI is installed (normal operation):**
```bash
$ sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"
>>> Running: sf project deploy start --source-dir force-app/main/default/classes --target-org DEMO-ORG
# [deployment proceeds immediately]
```

### ❌ **When SF CLI is missing:**
```bash
$ sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"
❌ Salesforce CLI (sf) not found!

Running environment check to help you get started...

🔍 Salesforce CLI Environment Check
==================================
[✗] Salesforce CLI (sf) not found in PATH
  Please install the Salesforce CLI from: https://developer.salesforce.com/tools/sfdxcli
[✗] Unable to list orgs (sf org list failed)
[!] No default org configured
==================================
[✗] Some critical issues found. Please address them before using the SF CLI wrappers.
```

### **How It Works:**
- **Silent Check**: Scripts automatically verify SF CLI availability
- **Zero Performance Impact**: Only activates when there's actually a problem
- **Intelligent Discovery**: Automatically finds and runs `sf-check` diagnostics
- **Cross-Platform**: Same experience on Bash and PowerShell
- **User-Friendly**: Clear error messages and actionable guidance

## Windows PowerShell Examples

For Windows users, here are the PowerShell equivalents of the bash examples:

### sf-deploy.ps1

```powershell
# Deploy multiple flexipages (specific files)
sf-deploy.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Page_Backup_With_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Deploy entire directory
sf-deploy.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"

# Deploy with specific tests
sf-deploy.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" `
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"
```

### sf-dry-run.ps1

```powershell
# Validate multiple flexipages (specific files)
sf-dry-run.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Validate entire directory
sf-dry-run.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"

# Validate with specific tests
sf-dry-run.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" `
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"
```

### sf-web-open.ps1

```powershell
# Open a specific org (default home)
sf-web-open.ps1 -o "DEMO-ORG"

# Open Setup Home of a target org
sf-web-open.ps1 -o "NUSHUB-DR2" -p "/lightning/setup/SetupOneHome/home"

# Get just the URL for scripting
sf-web-open.ps1 -o "NUSHUB-DR2" -U

# Open the current default org
sf-web-open.ps1
```

### Windows Common Workflows

```powershell
# 1. First, validate your deployment (specific file)
sf-dry-run.ps1 -o "DEMO-ORG" -s "force-app/main/default/classes/MyClass.cls"

# 2. If validation passes, deploy for real
sf-deploy.ps1 -o "DEMO-ORG" -s "force-app/main/default/classes/MyClass.cls"

# 3. Open the org to verify changes
sf-web-open.ps1 -o "DEMO-ORG"

# Alternative: Deploy entire directory
sf-dry-run.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"
sf-deploy.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"
```

## Prerequisites

- **Salesforce CLI (sf)**: Make sure you have the Salesforce CLI installed and configured
- **Shell Environment**:
  - **Unix/Linux/macOS**: Bash 4.0+ (macOS users may need to upgrade from the default Bash 3.x)
  - **Windows**: PowerShell 5.1+ (PowerShell Core 7+ recommended)
- **Authenticated Orgs**: Ensure you have authenticated to the target orgs using `sf org login`

## Common Workflows

### Deployment with Validation
```bash
# 1. First, validate your deployment (specific file)
sf-dry-run -o DEMO-ORG -s "force-app/main/default/classes/MyClass.cls"

# 2. If validation passes, deploy for real
sf-deploy -o DEMO-ORG -s "force-app/main/default/classes/MyClass.cls"

# 3. Open the org to verify changes
sf-web-open -o DEMO-ORG

# Alternative: Deploy entire directory
sf-dry-run -o DEMO-ORG -d "force-app/main/default/classes"
sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"
```

### Working with Multiple Files
```bash
# Deploy multiple related components (specific files)
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/classes/MyController.cls,force-app/main/default/classes/MyControllerTest.cls,force-app/main/default/aura/MyComponent"

# Deploy entire directories
sf-deploy -o DEMO-ORG -d "force-app/main/default/aura"
sf-deploy -o DEMO-ORG -d "force-app/main/default/lwc"
```

### Testing Specific Classes
```bash
# Deploy with specific test execution
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/classes/MyClass.cls" \
  -t "MyClassTest,RelatedClassTest"
```

## Features

- **Cross-Platform**: Available for both Unix/Linux/macOS (Bash) and Windows (PowerShell)
- **Automatic Environment Verification**: Scripts automatically check if SF CLI is available and run diagnostics if not
- **Error Handling**: All scripts include robust error handling
- **Help Documentation**: Each script includes comprehensive help accessible with `-h` (both Bash and PowerShell)
- **Flexible Input**: Support for both absolute and repository-relative paths
- **Command Echo**: Shows the actual `sf` command being executed for transparency
- **Multiple Sources**: Easy handling of multiple source directories and test classes
- **Parameter Validation**: Scripts validate required parameters and show helpful error messages

## Tips

1. **Use Tab Completion**: Most shells support tab completion for file paths when using these scripts
2. **Combine with Git**: Use `git status` to identify modified files for targeted deployments
3. **Org Aliases**: Set up meaningful org aliases with `sf org login` for easier reference
4. **Path Flexibility**: You can use both absolute paths and paths relative to your project root

## Troubleshooting

### Common Issues

1. **"Command not found"**: 
   - **Unix/Linux/macOS**: Ensure the scripts are executable and in your PATH
   - **Windows**: Check PowerShell execution policy and script location
2. **"No default org found"**: Specify the org parameter or set a default org with `sf config set target-org`
3. **"Source path not found"**: Verify file paths are correct relative to your project root
4. **Windows PowerShell Execution Policy**: If scripts won't run, check execution policy with `Get-ExecutionPolicy`

### Debug Mode

To see exactly what command is being executed, look for the ">>> Running:" output that each script prints before execution.

## Contributing

Feel free to extend these scripts or create additional wrappers for other Salesforce CLI commands. The scripts follow a consistent pattern:

**Bash Scripts:**
1. Help function with usage examples
2. Argument parsing with `getopts`
3. Command array building
4. Command execution with `exec`

**PowerShell Scripts:**
1. Parameter definitions with validation
2. Help function with usage examples
3. Parameter validation and processing
4. Command array building and execution

## License

These scripts are provided as-is for convenience. Modify and distribute as needed for your projects.