CWS-Lib-Bash Development

This skill provides development guidelines for contributing to the cws-lib-bash project, a cloud-native shell utility library.

Project Overview

cws-lib-bash is a modular bash library for cloud-native operations. It provides reusable shell functions organized by domain (networking, Docker, Kubernetes, etc.) with consistent error handling and logging.

Project Structure

```

cws-lib-bash/

├── bin/

│ ├── cws_bash_setup # Installation script

│ ├── cws_bash_env # Environment loader

│ └── cws_bash_run # Function executor

├── profile.d/ # Core functions loaded at shell startup

└── scripts/ # Domain-specific modules

├── network.sh

├── docker.sh

└── ...

```

Core Coding Patterns

Function Naming Convention

Use `snake_case` with the pattern `domain_action`:

```bash

network_test_connectivity

docker_list_containers

kubernetes_get_pods

```

Parameter Validation

Always validate required parameters:

```bash

function example_function() {

local var=${1:-}

[ -z "$var" ] && log error "Missing required parameter" && return ${RETURN_FAILURE:-1}

# Function logic here

}

```

Dependency Checking

Check for required commands before using them:

```bash

have docker || { log error "docker not found"; return ${RETURN_FAILURE:-1}; }

have kubectl || { log error "kubectl not found"; return ${RETURN_FAILURE:-1}; }

```

Logging

Use the `log` function with severity levels:

```bash

log info "Starting operation"

log notice "Configuration changed"

log warn "Deprecated feature used"

log error "Operation failed"

log fatal "Critical system error"

```

Error Codes

Use consistent return codes:

```bash

return ${RETURN_SUCCESS:-0} # Success

return ${RETURN_FAILURE:-1} # Failure

```

Safe Directory Navigation

Use `safe_pushd` and `safe_popd` for directory changes:

```bash

safe_pushd /target/directory || return ${RETURN_FAILURE:-1}

Perform operations

safe_popd || return ${RETURN_FAILURE:-1}

```

Development Workflow

1. Initial Setup

```bash

./bin/cws_bash_setup

```

2. Load Environment

```bash

source ./bin/cws_bash_env

```

3. Execute Functions

```bash

./bin/cws_bash_run <function_name> [arguments]

```

4. Syntax Checking

```bash

bash -n scripts/<file>.sh

```

5. Code Quality Check

Use VS Code task: "shellcheck: current file"

Creating New Modules

Adding a New Domain Module

1. Create `scripts/<domain>.sh`

2. Follow the core patterns outlined above

3. Add domain-specific functions using `domain_action` naming

4. Include proper error handling and logging

5. Add dependency checks for required commands

Platform Compatibility

Handle platform-specific logic:

```bash

if is_linux; then

# Linux-specific code

elif is_macos; then

# macOS-specific code

fi

```

Example Function Template

```bash

function example_clone() {

local dir=${1:-}

local url=${2:-}

# Validate parameters

[ -z "$dir" ] || [ -z "$url" ] && {

log error "Usage: example_clone <dir> <url>"

return ${RETURN_FAILURE:-1}

}

# Check dependencies

have git || {

log error "git not found"

return ${RETURN_FAILURE:-1}

}

# Execute operation

git_clone_into "$dir" "$url"

return ${RETURN_SUCCESS:-0}

}

```

Best Practices

1. **Always validate inputs** before using them

2. **Check dependencies** before executing commands

3. **Use consistent logging** throughout your functions

4. **Handle errors gracefully** with meaningful messages

5. **Return appropriate exit codes** for success/failure

6. **Document complex logic** with inline comments

7. **Test on both Linux and macOS** when possible

8. **Use safe directory operations** with pushd/popd wrappers

Integration Points

All functions are invoked through the `cws_bash_run` entry point, ensuring consistent environment setup and error handling.

Contributing

When adding new functionality: