added addl wrappers

2025-08-28 16:34:16 +08:00
parent a385484a69
commit 747aa90d26
17 changed files with 4265 additions and 21 deletions
--- a/README.md
+++ b/README.md
@@ -6,13 +6,28 @@ A collection of convenient wrapper scripts for common Salesforce CLI operations.

 ## Overview

-This toolkit provides four main utilities:
+This toolkit provides a suite of cross-platform wrappers to streamline common Salesforce CLI workflows:

+Core:
 - **`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

+Org and metadata:
+- **`sf-org-create` / `sf-org-create.ps1`** - Smart scratch org creation
+- **`sf-org-info` / `sf-org-info.ps1`** - Quick org info, limits, and context
+- **`sf-retrieve` / `sf-retrieve.ps1`** - Streamlined metadata retrieval (types, manifest, packages)
+
+Apex and tests:
+- **`sf-test-run` / `sf-test-run.ps1`** - Focused Apex test execution with coverage
+- **`sf-apex-run` / `sf-apex-run.ps1`** - Anonymous Apex execution (file or inline)
+
+Data and logs:
+- **`sf-data-export` / `sf-data-export.ps1`** - Export data via SOQL to CSV/JSON, optional Bulk API
+- **`sf-data-import` / `sf-data-import.ps1`** - Import CSV/JSON with insert/update/upsert
+- **`sf-logs-tail` / `sf-logs-tail.ps1`** - Real-time debug logs tail with filtering
+
 ## Installation

 ### Unix/Linux/macOS (Bash)
@@ -20,19 +35,30 @@ This toolkit provides four main utilities:
 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
+   chmod +x \
+     sf-deploy sf-dry-run sf-web-open sf-check \
+     sf-org-create sf-org-info sf-retrieve sf-test-run sf-apex-run \
+     sf-data-export sf-data-import sf-logs-tail
   ```
 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
-   ```
+# 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
+ln -s /path/to/sf-cli-wrapper/sf-org-create /usr/local/bin/sf-org-create
+ln -s /path/to/sf-cli-wrapper/sf-org-info /usr/local/bin/sf-org-info
+ln -s /path/to/sf-cli-wrapper/sf-retrieve /usr/local/bin/sf-retrieve
+ln -s /path/to/sf-cli-wrapper/sf-test-run /usr/local/bin/sf-test-run
+ln -s /path/to/sf-cli-wrapper/sf-apex-run /usr/local/bin/sf-apex-run
+ln -s /path/to/sf-cli-wrapper/sf-data-export /usr/local/bin/sf-data-export
+ln -s /path/to/sf-cli-wrapper/sf-data-import /usr/local/bin/sf-data-import
+ln -s /path/to/sf-cli-wrapper/sf-logs-tail /usr/local/bin/sf-logs-tail
+```

 ### Windows (PowerShell)

@@ -46,15 +72,125 @@ This toolkit provides four main utilities:
   # 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"
-   ```
+# 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"
+Set-Alias sf-org-create "C:\\path\\to\\sf-cli-wrapper\\sf-org-create.ps1"
+Set-Alias sf-org-info "C:\\path\\to\\sf-cli-wrapper\\sf-org-info.ps1"
+Set-Alias sf-retrieve "C:\\path\\to\\sf-cli-wrapper\\sf-retrieve.ps1"
+Set-Alias sf-test-run "C:\\path\\to\\sf-cli-wrapper\\sf-test-run.ps1"
+Set-Alias sf-apex-run "C:\\path\\to\\sf-cli-wrapper\\sf-apex-run.ps1"
+Set-Alias sf-data-export "C:\\path\\to\\sf-cli-wrapper\\sf-data-export.ps1"
+Set-Alias sf-data-import "C:\\path\\to\\sf-cli-wrapper\\sf-data-import.ps1"
+Set-Alias sf-logs-tail "C:\\path\\to\\sf-cli-wrapper\\sf-logs-tail.ps1"
+```

 ## Scripts

+### sf-org-create
+
+Smart scratch org creation with templates and intelligent defaults.
+
+Usage (bash):
+```bash
+sf-org-create [-a ALIAS] [-d DAYS] [-t TEMPLATE] [--no-namespace]
+```
+
+Usage (PowerShell):
+```powershell
+sf-org-create.ps1 -Alias "MySO" -DurationDays 7 -Template "config/project-scratch-def.json"
+```
+
+Examples:
+- Create with alias and duration: `sf-org-create -a SO -d 7`
+- Use a specific template: `sf-org-create -t config/project-scratch-def.json`
+
+### sf-org-info / sf-org-info.ps1
+
+Quick org information display with optional limits and listing authenticated orgs.
+
+Usage:
+```bash
+sf-org-info [-o ORG] [--limits] [--list]
+```
+```powershell
+sf-org-info.ps1 -TargetOrg "myorg" -Limits -Verbose
+```
+
+### sf-retrieve / sf-retrieve.ps1
+
+Streamlined metadata retrieval supporting metadata types, manifest, and package name.
+
+Usage:
+```bash
+sf-retrieve --types "ApexClass,CustomObject" | --manifest manifest/package.xml | --package-name MyPkg [--target-org ORG] [--output-dir DIR]
+```
+```powershell
+sf-retrieve.ps1 -MetadataTypes "ApexClass,CustomObject" -TargetOrg myorg -OutputDir retrieved
+```
+
+### sf-test-run / sf-test-run.ps1
+
+Focused Apex test execution with better formatting, coverage, and wait control.
+
+Usage:
+```bash
+sf-test-run --classes "A,B" | --methods "A.m1,B.m2" | --level RunLocalTests [--coverage] [--wait 15] [--target-org ORG]
+```
+```powershell
+sf-test-run.ps1 -TestClasses "ApexTest1,ApexTest2" -Coverage -Wait 15
+```
+
+### sf-apex-run / sf-apex-run.ps1
+
+Execute anonymous Apex from file or inline code.
+
+Usage:
+```bash
+sf-apex-run --file scripts/setup.apex | --code "System.debug('hi');" [--target-org ORG]
+```
+```powershell
+sf-apex-run.ps1 -File "scripts/setup.apex" -TargetOrg dev
+```
+
+### sf-data-export / sf-data-export.ps1
+
+Export data via SOQL to CSV/JSON with optional Bulk API.
+
+Usage:
+```bash
+sf-data-export --query "SELECT Id, Name FROM Account" | --file query.soql | --sobject Account [--format csv|json] [--bulk] [--output out.csv]
+```
+```powershell
+sf-data-export.ps1 -Query "SELECT Id FROM User" -Format json -Output users.json
+```
+
+### sf-data-import / sf-data-import.ps1
+
+Import CSV/JSON with insert/update/upsert operations.
+
+Usage:
+```bash
+sf-data-import --file data.csv --sobject Account --operation insert|update|upsert [--external-id Field] [--bulk]
+```
+```powershell
+sf-data-import.ps1 -File data.json -SObject Contact -Operation upsert -ExternalId Email
+```
+
+### sf-logs-tail / sf-logs-tail.ps1
+
+Real-time debug logs tail with filtering, levels, and Apex-only mode.
+
+Usage:
+```bash
+sf-logs-tail [--target-org ORG] [--user-id USER] [--level DEBUG] [--duration 60] [--filter PATTERN] [--apex-only]
+```
+```powershell
+sf-logs-tail.ps1 -TargetOrg sandbox -Level DEBUG -Duration 60 -ApexOnly -Filter "MyClass"
+```
+
 ### sf-deploy

 Wrapper for `sf project deploy start` that simplifies deploying multiple source files with optional test execution.
@@ -178,7 +314,7 @@ sf-check -v

 ## Automatic Environment Verification

-All wrapper scripts (`sf-deploy`, `sf-dry-run`, `sf-web-open`) include built-in environment verification:
+All wrapper scripts (deploy, dry-run, web-open, org-create, org-info, retrieve, test-run, apex-run, data-export, data-import, logs-tail) include built-in environment verification:

 ### ✅ **When SF CLI is installed (normal operation):**
 ```bash
@@ -265,6 +401,28 @@ sf-web-open.ps1

 ### Windows Common Workflows

+Additional helpers (PowerShell):
+```powershell
+# Org creation
+sf-org-create.ps1 -Alias "SO" -DurationDays 7
+
+# Retrieve metadata
+sf-retrieve.ps1 -Manifest "manifest/package.xml" -TargetOrg "dev"
+
+# Run tests with coverage
+sf-test-run.ps1 -TestLevel RunLocalTests -Coverage -Wait 15
+
+# Execute anonymous Apex
+sf-apex-run.ps1 -Code "System.debug('Hello');" -TargetOrg dev
+
+# Data export and import
+sf-data-export.ps1 -SObject Account -Format csv -Output accounts.csv
+sf-data-import.ps1 -File accounts.csv -SObject Account -Operation insert
+
+# Tail logs
+sf-logs-tail.ps1 -Level DEBUG -Duration 30 -ApexOnly
+```
+
 ```powershell
 # 1. First, validate your deployment (specific file)
 sf-dry-run.ps1 -o "DEMO-ORG" -s "force-app/main/default/classes/MyClass.cls"
@@ -328,13 +486,13 @@ sf-deploy -o DEMO-ORG \
 ## 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
+- **Automatic Environment Verification**: All wrappers auto-check SF CLI and run diagnostics when missing
+- **Consistent UX**: Arguments and output styling are aligned across Bash and PowerShell
+- **Error Handling**: Robust input validation and actionable errors
+- **Help Documentation**: Each script includes comprehensive help (-h or -Help)
+- **Flexible Input**: Supports 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
+- **Focused Workflows**: Deploy, validate, retrieve, test, run Apex, manage orgs, data import/export, and tail logs

 ## Tips