@objctp/opencode-shell-routines 1.2.0

package/skills/shell-best-practices/references/patterns.md

@@ -0,0 +1,386 @@
+# Common Bash Patterns
+
+## Argument Parsing
+
+### Basic positional arguments
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    echo "Usage: $0 <input> <output>" >&2
+    exit 2
+}
+
+[[ $# -eq 2 ]] || usage
+
+input="$1"
+output="$2"
+```
+
+### getopts (flag-based)
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+verbose=0
+output_file=""
+
+while getopts "vo:" opt; do
+    case "$opt" in
+        v) verbose=1 ;;
+        o) output_file="$OPTARG" ;;
+        \?) echo "Invalid option: -$OPTARG" >&2; exit 2 ;;
+    esac
+done
+
+shift $((OPTIND - 1))
+```
+
+## Temporary Files
+
+### Safe temp file with cleanup
+```bash
+tmp_file=$(mktemp)
+trap 'rm -f "$tmp_file"' EXIT
+
+# Process with temp file
+process_data > "$tmp_file"
+result=$(cat "$tmp_file")
+```
+
+### Safe temp directory
+```bash
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+
+# Create files in temp directory
+output="$tmp_dir/output.txt"
+```
+
+## Arrays
+
+### Iteration
+```bash
+items=("apple" "banana" "cherry")
+for item in "${items[@]}"; do
+    echo "$item"
+done
+```
+
+### Building array from command output
+```bash
+readarray -t files < <(find . -name "*.txt" -type f)
+for file in "${files[@]}"; do
+    process "$file"
+done
+```
+
+### Associative arrays (bash 4+)
+```bash
+declare -A config
+config[host]="localhost"
+config[port]="8080"
+
+for key in "${!config[@]}"; do
+    echo "$key = ${config[$key]}"
+done
+```
+
+## String Manipulation
+
+### Parameter expansion (bash 4+)
+```bash
+string="Hello, World!"
+
+# Uppercase
+echo "${string^^}"  # HELLO, WORLD!
+
+# Lowercase
+echo "${string,,}"  # hello, world!
+
+# Remove suffix
+path="/path/to/file.txt"
+echo "${path%.txt}"  # /path/to/file
+
+# Remove prefix
+echo "${path##*/}"  # file.txt
+
+# Replace first match
+echo "${string/World/Bash}"  # Hello, Bash!
+
+# Replace all matches
+echo "${string//l/L}"  # HeLLo, WorLd!
+```
+
+### Use braces for variable expansion
+```bash
+# BAD - ambiguous without braces
+echo "$var_name"      # Is this ${var_name} or ${var}_name?
+
+# GOOD - braces make intent explicit
+echo "${var}_name"
+echo "${var_name}"
+
+# GOOD - braces required for array, length, and manipulation
+echo "${items[@]}"
+echo "${#items[@]}"
+echo "${var:-default}"
+```
+
+### Indirect expansion
+```bash
+# Access variable whose name is stored in another variable
+var_name="colour"
+colour="blue"
+
+echo "${!var_name}"  # blue
+
+# Use case: dynamic config lookup
+declare -A config
+config[host]="localhost"
+config[port]="8080"
+
+for key in host port; do
+    echo "${config[$key]}"
+done
+```
+
+### Numeric vs string comparison
+```bash
+# BAD - '>' inside [[ ]] is lexicographic: "9" < "7"
+if [[ $count > 7 ]]; then ...
+
+# GOOD - use (( )) for arithmetic
+if (( count > 7 )); then ...
+
+# GOOD - or -gt inside [[ ]]
+if [[ $count -gt 7 ]]; then ...
+```
+
+### Exact equality vs pattern matching in [[ ]]
+```bash
+bar="*.txt"
+
+# BAD - unquoted RHS enables glob pattern matching
+[[ "file.txt" = $bar ]] && echo yes   # matches!
+
+# GOOD - quote RHS for exact string equality
+[[ "file.txt" = "$bar" ]] && echo yes # no match
+
+# For intentional glob matching, leave RHS unquoted
+[[ "file.txt" == *.txt ]]              # matches
+```
+
+### IFS splitting drops trailing empty fields
+```bash
+# BAD - trailing empty field silently lost
+IFS=, read -ra arr <<< "a,b,"
+echo "${#arr[@]}"  # 2, not 3
+
+# GOOD - use -d '' to preserve trailing empties
+IFS=, read -d '' -ra arr <<< "a,b,"
+echo "${#arr[@]}"  # 3
+
+# GOOD - for CSV rows, handle trailing empties explicitly
+line="a,b,"
+IFS=, read -ra arr <<< "$line"
+expected=3
+while (( ${#arr[@]} < expected )); do
+    arr+=("")
+done
+```
+
+## File Operations
+
+### Check file existence and type
+```bash
+if [[ -f "$file" ]]; then
+    echo "Regular file exists"
+elif [[ -d "$file" ]]; then
+    echo "Directory exists"
+elif [[ -e "$file" ]]; then
+    echo "Something exists (not regular file or directory)"
+else
+    echo "Does not exist"
+fi
+```
+
+**Note**: `[[ -e ]]` returns false for broken symlinks. Use `[[ -L ]]` to test symlink existence regardless of target:
+```bash
+# BAD - broken symlinks report as non-existent
+if [[ -e "$link" ]]; then ... fi   # false for broken symlink
+
+# GOOD - test the link itself
+if [[ -L "$link" ]]; then ... fi   # true for any symlink
+
+# GOOD - check both link existence AND target
+if [[ -L "$link" && -e "$link" ]]; then
+    echo "Symlink with valid target"
+elif [[ -L "$link" ]]; then
+    echo "Broken symlink"
+fi
+```
+
+### Read file line by line
+```bash
+while IFS= read -r line; do
+    process_line "$line"
+done < "$input_file"
+```
+
+### Process files in directory
+```bash
+for file in *.txt; do
+    [[ -f "$file" ]] || continue
+    process "$file"
+done
+```
+
+### Use `--` before variable file arguments
+```bash
+# BAD - filename starting with '-' parsed as option
+rm "$file"
+cp "$src" "$dst"
+
+# GOOD - '--' ends option parsing
+rm -- "$file"
+cp -- "$src" "$dst"
+
+# GOOD - './' prefix prevents dash interpretation
+mv "./$file" "$dest"
+```
+
+### Safely rewrite a file in-place
+```bash
+# BAD - file truncated before cat reads it
+cat file | sort > file        # file is now empty
+grep pattern file > file      # file is now empty
+
+# GOOD - write to temp file, then replace
+sort file > tmp && mv tmp file
+
+# GOOD - use sponge (moreutils) for in-place
+sort file | sponge file
+```
+
+### Redirect stderr to /dev/null, never close it
+```bash
+# BAD - closing stderr can cause programs to crash or misbehave
+cmd 2>&-
+
+# GOOD - redirect to /dev/null instead
+cmd 2>/dev/null
+
+# GOOD - suppress both stdout and stderr
+cmd >/dev/null 2>&1
+```
+
+### Preserve variables set inside a read loop
+```bash
+# BAD - pipe creates subshell; counter lost
+count=0
+cat file | while IFS= read -r line; do
+    ((count++))
+done
+echo "$count"  # always 0
+
+# GOOD - process substitution keeps same shell
+count=0
+while IFS= read -r line; do
+    ((count++))
+done < <(cat file)
+echo "$count"  # correct count
+```
+
+## Parallel Processing
+
+### Simple parallel with xargs
+```bash
+find . -name "*.log" -print0 | \
+    xargs -0 -P 4 -I {} process_log "{}"
+```
+
+### Background jobs with wait
+```bash
+pids=()
+for item in "${items[@]}"; do
+    process "$item" &
+    pids+=($!)
+done
+
+# Wait for all background jobs
+for pid in "${pids[@]}"; do
+    wait "$pid"
+done
+```
+
+## Progress Indication
+
+### Simple counter
+```bash
+total=$(wc -l < "$file")
+current=0
+
+while IFS= read -r line; do
+    ((current++))
+    printf "\rProcessing: %d/%d" "$current" "$total"
+    process "$line"
+done
+printf "\n"
+```
+
+## Exit Code Handling
+
+### Check command success
+```bash
+if ! command_that_might_fail; then
+    echo "Command failed" >&2
+    exit 1
+fi
+```
+
+### Capture and check exit code
+```bash
+if output=$(some_command); then
+    echo "Success: $output"
+else
+    exit_code=$?
+    echo "Failed with code: $exit_code" >&2
+    exit "$exit_code"
+fi
+```
+
+## Input Validation
+
+### Validate numeric input
+```bash
+is_number() {
+    local value="$1"
+    [[ "$value" =~ ^[0-9]+$ ]]
+}
+
+# Usage
+if is_number "$port"; then
+    echo "Valid port number"
+fi
+```
+
+### Validate within range
+```bash
+validate_port() {
+    local port="$1"
+    (( port >= 1 && port <= 65535 ))
+}
+```
+
+### Validate required arguments
+```bash
+validate_inputs() {
+    local name="$1"
+    local port="$2"
+
+    [[ -n "$name" ]] || { echo "Error: name is required" >&2; return 1; }
+    validate_port "$port" || { echo "Error: port out of range" >&2; return 1; }
+}
+```

package/skills/shell-best-practices/references/security.md

@@ -0,0 +1,195 @@
+# Writing Secure Shell Scripts
+
+Preventive patterns to apply while writing shell scripts. For auditing existing scripts for security vulnerabilities (destructive commands, credential exposure, system file risks), use `shell-security` instead.
+
+## Command Injection Prevention
+
+### NEVER use eval
+```bash
+# BAD - User can execute arbitrary commands
+eval "echo $user_input"
+
+# GOOD - Use arrays or direct execution
+echo "$user_input"
+```
+
+### NEVER pipe to sh/bash
+```bash
+# BAD - Downloads and executes untrusted code
+curl http://example.com/script.sh | sh
+
+# GOOD - Download, review, then execute
+curl -O http://example.com/script.sh
+less script.sh
+sh script.sh
+```
+
+### ALWAYS quote variables in command positions
+```bash
+# BAD - Word splitting and globbing
+func $user_var
+
+# GOOD - Properly quoted
+func "$user_var"
+```
+
+## Input Validation
+
+### Validate filenames against path traversal
+```bash
+validate_filename() {
+    local filename="$1"
+
+    # Reject paths with directory traversal
+    if [[ "$filename" == *".."* ]]; then
+        echo "Error: invalid filename" >&2
+        return 1
+    fi
+
+    # Reject absolute paths if not expected
+    if [[ "$filename" == /* ]]; then
+        echo "Error: absolute paths not allowed" >&2
+        return 1
+    fi
+
+    # Only allow safe characters
+    if [[ ! "$filename" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+        echo "Error: filename contains invalid characters" >&2
+        return 1
+    fi
+}
+```
+
+For type/range validation helpers (e.g. `is_number`, `validate_port`), see `references/patterns.md`.
+
+### Sanitise environment variables
+```bash
+# Clear PATH before using untrusted input
+if [[ "$untrusted_mode" == "true" ]]; then
+    export PATH="/usr/bin:/bin"
+fi
+```
+
+## Secrets Handling
+
+### NEVER hardcode credentials
+```bash
+# BAD
+api_key="sk-live-1234567890abcdef"
+
+# GOOD - Read from environment
+api_key="${API_KEY:-}"
+[[ -n "$api_key" ]] || { echo "Error: API_KEY not set" >&2; exit 1; }
+```
+
+### Prevent secrets in process list
+```bash
+# BAD - Secret visible in ps
+curl -H "Authorization: Bearer $secret_token" https://api.example.com
+
+# GOOD - Use file for secrets
+echo "Authorization: Bearer $secret_token" > "$tmp_headers"
+curl -H @"$tmp_headers" https://api.example.com
+rm -f "$tmp_headers"
+```
+
+### Prevent secrets in logs
+```bash
+# Redirect debug output that may contain secrets
+process_with_secrets 2>/dev/null
+
+# Or filter sensitive patterns
+process_with_secrets 2>&1 | grep -v "password\|token\|secret"
+```
+
+## Temporary Files
+
+### ALWAYS use mktemp
+```bash
+# BAD - Predictable filename, race condition
+tmp_file="/tmp/my_script_$$"
+
+# GOOD - Atomic, unpredictable
+tmp_file=$(mktemp)
+trap 'rm -f "$tmp_file"' EXIT
+```
+
+### Set restrictive permissions on temp files
+```bash
+tmp_file=$(mktemp)
+chmod 600 "$tmp_file"
+```
+
+## File Permissions
+
+### Use restrictive defaults
+```bash
+# Create files with owner-only permissions
+umask 077
+
+# Or set explicitly
+output_file=$(mktemp)
+chmod 600 "$output_file"
+```
+
+### Avoid world-writable locations
+```bash
+# BAD - /tmp is world-writable
+output="/tmp/data.txt"
+
+# GOOD - Use user's cache
+output="$HOME/.cache/script/data.txt"
+mkdir -p "$(dirname "$output")"
+```
+
+## Safe Command Execution
+
+### Use arrays for arguments
+```bash
+# BAD - Word splitting
+files="*.txt"
+cat $files
+
+# GOOD - Proper expansion
+files=("*.txt")
+cat "${files[@]}"
+```
+
+### Use set -f to disable globbing
+```bash
+# Disable glob expansion when processing untrusted input
+set -f
+process_untrusted "$user_input"
+set +f
+```
+
+## Signal Handling
+
+### Clean up on interruption
+```bash
+cleanup() {
+    rm -f "$tmp_file"
+    rm -rf "$tmp_dir"
+    echo "Cleaned up temporary files" >&2
+}
+
+trap cleanup EXIT INT TERM HUP
+
+tmp_file=$(mktemp)
+tmp_dir=$(mktemp -d)
+```
+
+### Prevent partial state on exit
+```bash
+cleanup() {
+    # Remove incomplete output
+    [[ -f "${output}.partial" ]] && rm -f "${output}.partial"
+}
+
+trap cleanup EXIT
+
+# Write to partial file, rename on success
+output="result.txt"
+process_data > "${output}.partial"
+mv "${output}.partial" "$output"
+```

package/skills/shell-debugging/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: shell-debugging
+description: Debug a failing bash script: reproduce the failure, isolate the cause with non-invasive tracing (bash -x, bash -n, ShellCheck), then apply and verify the fix. Use when a script errors at runtime, crashes, exits non-zero, or produces wrong output ("debug this script", "fix my script", "why is this failing"). For a script that works but runs slowly, use shell-profiling; for quality review of a working script, use shell-review.
+allowed-tools: Read, Edit, Bash, Grep, Glob
+argument-hint: [script-path]
+---
+
+# Shell Debugging Skill
+
+Guides systematic debugging of bash scripts to identify and resolve issues efficiently.
+
+**Scope**: This skill handles runtime failures — scripts that error, crash, or produce wrong output. For quality assessment of a working script, use `shell-review` instead.
+
+**Design principle**: Never leave debug instrumentation in the target script. Use non-invasive methods (`bash -x`) first; when targeted tracing is needed, instrument a temporary copy and discard it afterwards.
+
+## Debugging Workflow
+
+### 1. Gather Information
+
+**Target script:** `$ARGUMENTS`
+
+If `$ARGUMENTS` is not provided, ask the user which script needs debugging.
+
+Understand the failure:
+
+- **Error message**: What is the exact error?
+- **Exit code**: What is `$?` after the failing command?
+- **Failure point**: Where exactly does the script fail?
+- **Reproduction**: Can the failure be reproduced consistently?
+
+### 2. Read the Target Script
+
+Read `$ARGUMENTS` to understand:
+
+- Overall structure and purpose
+- Functions called near the failure point
+- Variable dependencies
+- Error handling patterns
+
+### 3. Enable Debug Mode
+
+**Non-invasive** — run with tracing from the command line, no file modification:
+
+```bash
+bash -x script.sh args
+```
+
+- `+` prefix indicates the command being executed
+- Variables are expanded before printing
+
+**Targeted tracing** — when you need tracing around a specific section only, create a temporary copy:
+
+```bash
+cp script.sh /tmp/script.debug.sh
+# Add set -x / set +x around the suspect section in the copy
+bash /tmp/script.debug.sh args
+rm /tmp/script.debug.sh
+```
+
+### 4. Syntax Validation
+
+```bash
+bash -n script.sh
+```
+
+### 5. Incremental Execution
+
+**Warning**: `source` executes all top-level code in the script. Before sourcing a broken script, inspect it for side effects (file operations, network calls, deployments). Consider using a container or VM for untrusted scripts.
+
+```bash
+# Source the script to load functions
+source script.sh
+
+# Call functions individually with test data
+your_function "test_input"
+```
+
+### 6. Identify the Issue
+
+Consult `references/debugging-guide.md` for:
+
+- Error pattern tables and fixes (unbound variables, pipelines, subshells, whitespace)
+- Advanced techniques: custom PS4, timing, call logging
+- ShellCheck quick-reference table for common warning codes
+
+### 7. Apply the Fix
+
+Make the minimal change that resolves the root cause, not the symptom.
+
+### 8. Verify
+
+- Re-run the originally failing invocation — it now succeeds
+- `bash -n` is clean; no new errors introduced
+- No debug instrumentation remains in the script
+
+**Done when** the reported failure no longer reproduces under the original invocation, `bash -n` and ShellCheck are clean, and the script holds no leftover `set -x` or debug prints.
+
+## Additional Resources
+
+### References
+
+- `references/debugging-guide.md` -- Error pattern tables, debugging checklist, common issue solutions, advanced techniques (custom PS4, timing, call logging), ShellCheck quick reference
+
+Always read all references and examples before producing output.
+
+### Examples
+
+- `examples/debug-session.md` -- Walks through diagnosing an unbound variable error from start to finish
+
+## Integration
+
+- **`shell-best-practices`** -- Prevent issues before they occur
+- **`shell-review`** -- Quality assessment once the script is working
+- **`shell-profiling`** -- For scripts that work correctly but run too slowly. See profiling workflow for timing, tracing, and benchmarking.
+- **`/shell-audit`** command -- Comprehensive quality checks