smom-dbis-138/scripts/REFACTORING_GUIDE.md

Script Refactoring Guide

This guide explains how to refactor existing scripts to use the new common library structure.

Quick Start

Before (Old Pattern)

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

# Load subscription ID
if [ -f "$PROJECT_ROOT/.env" ]; then
    export $(grep -v '^#' "$PROJECT_ROOT/.env" | grep AZURE_SUBSCRIPTION_ID | xargs)
fi

SUBSCRIPTION_ID="${AZURE_SUBSCRIPTION_ID:-fc08d829-4f14-413d-ab27-ce024425db0b}"

# Check Azure CLI
if ! command -v az &> /dev/null; then
    echo -e "${RED}Error: Azure CLI not found${NC}"
    exit 1
fi

# Check Azure login
az account show &> /dev/null || {
    echo -e "${RED}Error: Not logged in to Azure${NC}"
    exit 1
}

az account set --subscription "$SUBSCRIPTION_ID" &> /dev/null || true

echo -e "${GREEN}Starting script...${NC}"

After (New Pattern)

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../lib/init.sh"

# Initialize Azure
SUBSCRIPTION_ID="$(get_subscription_id)"
ensure_azure_cli || exit 1
set_subscription "$SUBSCRIPTION_ID" || true

log_info "Starting script..."

Migration Checklist

Step 1: Add Library Sourcing

Replace:

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"

With:

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../lib/init.sh"

Note: PROJECT_ROOT is automatically set by the library.

Step 2: Remove Color Definitions

Remove:

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

Use logging functions instead:

log_info "Message"
log_warn "Warning"
log_error "Error"
log_success "Success"

Step 3: Replace Echo Statements

Old	New
echo -e "${GREEN}Success${NC}"	log_success "Success"
echo -e "${RED}Error${NC}"	log_error "Error"
echo -e "${YELLOW}Warning${NC}"	log_warn "Warning"
echo "Info"	log_info "Info"

Step 4: Replace Azure CLI Checks

Remove:

if ! command -v az &> /dev/null; then
    echo -e "${RED}Error: Azure CLI not found${NC}"
    exit 1
fi

az account show &> /dev/null || {
    echo -e "${RED}Error: Not logged in${NC}"
    exit 1
}

Replace with:

ensure_azure_cli || exit 1

Step 5: Replace Subscription Loading

Remove:

if [ -f "$PROJECT_ROOT/.env" ]; then
    export $(grep -v '^#' "$PROJECT_ROOT/.env" | grep AZURE_SUBSCRIPTION_ID | xargs)
fi

SUBSCRIPTION_ID="${AZURE_SUBSCRIPTION_ID:-fc08d829-4f14-413d-ab27-ce024425db0b}"
az account set --subscription "$SUBSCRIPTION_ID" &> /dev/null || true

Replace with:

SUBSCRIPTION_ID="$(get_subscription_id)"
set_subscription "$SUBSCRIPTION_ID" || true

Step 6: Replace Region Code Mappings

Remove large declare -A REGION_CODES blocks and replace with:

# Get all regions
get_all_regions

# Get specific region code
CODE=$(get_region_code "westeurope")  # Returns "wst"

# Get region name from code
REGION=$(get_region_name "wst")  # Returns "westeurope"

Common Patterns

Pattern 1: Script with Azure Operations

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../lib/init.sh"

ensure_azure_cli || exit 1

log_section "Script Title"

# Your script logic here

Pattern 2: Script with Region Iteration

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../lib/init.sh"

ensure_azure_cli || exit 1

log_section "Processing Regions"

while IFS=':' read -r region_name region_code; do
    log_info "Processing $region_name ($region_code)..."
    # Your logic here
done < <(get_all_regions)

Pattern 3: Script with Error Handling

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../lib/init.sh"

ensure_azure_cli || exit 1

ERRORS=()

# Process items
for item in "${ITEMS[@]}"; do
    if ! process_item "$item"; then
        ERRORS+=("$item")
        log_error "Failed to process $item"
    else
        log_success "Processed $item"
    fi
done

# Report errors
if [ ${#ERRORS[@]} -gt 0 ]; then
    log_warn "Failed to process ${#ERRORS[@]} items"
    exit 1
fi

log_success "All items processed successfully"

Available Library Functions

Logging (lib/common/logging.sh)

• log_debug "message" - Debug level log
• log_info "message" - Info level log
• log_warn "message" - Warning log
• log_error "message" - Error log
• log_success "message" - Success message
• log_failure "message" - Failure message
• log_section "title" - Section header
• log_subsection "title" - Subsection header

Colors (lib/common/colors.sh)

• color_red "text" - Red text
• color_green "text" - Green text
• color_yellow "text" - Yellow text
• color_blue "text" - Blue text
• color_cyan "text" - Cyan text

Azure CLI (lib/azure/cli.sh)

• check_azure_cli - Check if Azure CLI is installed
• check_azure_login - Check if logged in
• ensure_azure_cli - Ensure CLI is ready (installed + logged in)
• get_current_subscription - Get current subscription ID
• get_current_subscription_name - Get current subscription name

Configuration (lib/config/)

• get_subscription_id - Get subscription ID from env or default
• set_subscription "id" - Set Azure subscription
• get_region_code "name" - Get 3-char region code
• get_region_name "code" - Get region name from code
• get_all_regions - Get all regions (name:code format)
• is_valid_region_code "code" - Validate region code

Utilities (lib/common/utils.sh)

• require_command "cmd" ["hint"] - Require command exists
• command_exists "cmd" - Check if command exists
• confirm "prompt" ["default"] - Confirm action
• is_dry_run - Check if in dry-run mode
• print_header "title" ["width"] - Print header box

Testing Refactored Scripts

1. Test with --dry-run if supported
2. Verify output formatting matches original
3. Check error messages are clear
4. Ensure backward compatibility if script is called by others

Examples

See scripts/azure/check-naming-conventions.sh.refactored for a complete example of a refactored script.

# Example migrated scripts (as references):
# - scripts/deployment/fix-resource-groups-and-keyvaults.sh
# - scripts/azure/list-all-resources.sh
# - scripts/key-management/manage-keyvaults.sh
# - scripts/key-management/azure-keyvault-setup.sh
# - scripts/key-management/store-nodes-in-keyvault.sh

Testing

# Syntax check only (no execution):
bash -n scripts/azure/list-all-resources.sh
bash -n scripts/key-management/manage-keyvaults.sh
bash -n scripts/key-management/azure-keyvault-setup.sh
bash -n scripts/key-management/store-nodes-in-keyvault.sh

# Dry run (where supported):
DRY_RUN=1 scripts/key-management/store-nodes-in-keyvault.sh