@objctp/opencode-shell-routines 1.2.0

package/skills/shell-debugging/examples/debug-session.md

@@ -0,0 +1,165 @@
+# Example: Debugging an Unbound Variable Error
+
+## The Failing Script
+
+```bash
+#!/usr/bin/env bash
+# deploy.sh - Deploy application to environment
+set -euo pipefail
+
+ENV="${1:-}"
+DRY_RUN="${2:-false}"
+
+validate_env() {
+    local env="$1"
+    case "$env" in
+        staging|production) ;;
+        *)
+            echo "Error: invalid environment '$env'" >&2
+            return 1
+            ;;
+    esac
+}
+
+build_image() {
+    local tag="$1"
+    docker build -t "$tag" .
+}
+
+push_image() {
+    local tag="$1"
+    docker push "$tag"
+}
+
+deploy() {
+    local env="$1"
+    local tag="myapp:${COMMIT_HASH}"
+    build_image "$tag"
+    push_image "$tag"
+    kubectl set image "deployment/myapp-${env}" "myapp=${tag}"
+}
+
+# Main
+validate_env "$ENV"
+
+if [[ "$DRY_RUN" == "true" ]]; then
+    echo "DRY RUN: would deploy to $ENV"
+    exit 0
+fi
+
+deploy "$ENV"
+echo "Deployed to $ENV"
+```
+
+## Step 1: Observe the Error
+
+```bash
+$ bash deploy.sh staging
+deploy.sh: line 42: COMMIT_HASH: unbound variable
+```
+
+The script exits with an unbound variable error. The message tells us the variable name (`COMMIT_HASH`) and the line number (42, inside `deploy()`).
+
+Exit code:
+
+```bash
+$ echo $?
+1
+```
+
+## Step 2: Syntax Check
+
+Before investigating further, confirm the script has no syntax errors:
+
+```bash
+$ bash -n deploy.sh
+# No output -- syntax is valid
+```
+
+The problem is not a syntax issue. It is a runtime error caused by `set -u` (nounset) combined with a missing variable.
+
+## Step 3: Enable Trace Mode
+
+Add `set -x` to see the execution flow leading to the failure:
+
+```bash
+$ bash -x deploy.sh staging
++ ENV=staging
++ DRY_RUN=false
++ validate_env staging
++ local env=staging
++ case staging in
++ return 0
++ [[ false == \t\r\u\e ]]
++ deploy staging
++ local env=staging
++ local tag=myapp:
+deploy.sh: line 42: COMMIT_HASH: unbound variable
+```
+
+The trace shows `tag=myapp:` -- the `COMMIT_HASH` variable is empty at expansion time, and because of `set -u`, bash treats it as an error rather than expanding to an empty string.
+
+The root cause is clear: `COMMIT_HASH` is never set in the script. It was presumably meant to be injected from the environment or derived from git.
+
+## Step 4: ShellCheck for Additional Issues
+
+```bash
+$ shellcheck deploy.sh
+
+In deploy.sh line 42:
+    local tag="myapp:${COMMIT_HASH}"
+                         ^---------^ SC2153: Possible misspelling: COMMIT_HASH (not declared)
+```
+
+ShellCheck confirms the variable is undeclared. It also catches the missing guard.
+
+## Step 5: Apply the Fix
+
+The variable should either be derived or have a sensible default:
+
+```bash
+# Option A: Derive from git
+COMMIT_HASH="${COMMIT_HASH:-$(git rev-parse --short HEAD 2>/dev/null || echo unknown)}"
+
+# Option B: Require it explicitly
+if [[ -z "${COMMIT_HASH:-}" ]]; then
+    echo "Error: COMMIT_HASH must be set" >&2
+    exit 1
+fi
+```
+
+After applying option A near the top of the script:
+
+```bash
+#!/usr/bin/env bash
+# deploy.sh - Deploy application to environment
+set -euo pipefail
+
+ENV="${1:-}"
+DRY_RUN="${2:-false}"
+COMMIT_HASH="${COMMIT_HASH:-$(git rev-parse --short HEAD 2>/dev/null || echo unknown)}"
+```
+
+## Step 6: Verify the Fix
+
+```bash
+$ bash deploy.sh staging true
+DRY RUN: would deploy to staging
+
+$ bash -x deploy.sh staging true
++ ENV=staging
++ DRY_RUN=true
+++ git rev-parse --short HEAD
++ COMMIT_HASH=a1b2c3d
++ validate_env staging
++ local env=staging
++ case staging in
++ return 0
++ [[ true == \t\r\u\e ]]
++ echo 'DRY RUN: would deploy to staging'
+DRY RUN: would deploy to staging
++ exit 0
+```
+
+The script now resolves `COMMIT_HASH` from git and completes without errors.
+

package/skills/shell-debugging/references/debugging-guide.md

@@ -0,0 +1,336 @@
+# Shell Script Debugging Guide
+
+## Quick Reference
+
+### Enable Debug Output
+```bash
+# Print each command before execution
+set -x
+
+# Print script lines as read
+set -v
+
+# Show function calls in trace
+set -o functrace
+```
+
+### Disable Debug Output
+```bash
+set +x
+set +v
+set +o functrace
+```
+
+### Syntax Check
+```bash
+# Parse without executing
+bash -n script.sh
+
+# Check all .sh files
+for f in *.sh; do bash -n "$f"; done
+```
+
+## Debugging Checklist
+
+Use this checklist when troubleshooting:
+
+### Environment Issues
+- [ ] Correct shell? (`echo $SHELL`, `ps -p $$`)
+- [ ] Bash version compatible? (`bash --version`)
+- [ ] Required tools installed? (`command -v toolname`)
+- [ ] PATH correct? (`echo $PATH`)
+- [ ] Environment variables set? (`env | grep VAR`)
+
+### Syntax Issues
+- [ ] Run `bash -n script.sh` for syntax errors
+- [ ] Check paired quotes: `'` and `"`
+- [ ] Check paired brackets: `(`, `[`, `{`, `((`, `[[`
+- [ ] Check line continuation: `\` at end of lines
+- [ ] No Windows line endings? (`file script.sh`)
+
+### Variable Issues
+- [ ] Variable defined before use?
+- [ ] Variable scope correct? (`local` vs global)
+- [ ] Proper quoting? `"$var"` not `$var`
+- [ ] Default value needed? `${var:-default}`
+- [ ] Indirect reference correct? `${!varname}`
+
+### Logic Issues
+- [ ] Correct comparison operator?
+  - Strings: `[[ "$a" == "$b" ]]` or `[ "$a" = "$b" ]`
+  - Numbers: `(( a == b ))` or `[ "$a" -eq "$b" ]`
+- [ ] Test returns expected value? `echo $?`
+- [ ] Exit codes correct? 0=success, non-zero=failure
+- [ ] Pipeline error handled? `set -o pipefail`
+
+### File Issues
+- [ ] File exists? `[[ -f "$file" ]]`
+- [ ] Readable? `[[ -r "$file" ]]`
+- [ ] Correct path? Absolute vs relative
+- [ ] Permission problems? `ls -l "$file"`
+
+## Common Patterns
+
+### Debug Function
+
+```bash
+debug() {
+    if [[ "${DEBUG:-0}" == "1" ]]; then
+        echo "[DEBUG] $*" >&2
+    fi
+}
+
+# Usage
+DEBUG=1
+debug "Variable value: $var"
+```
+
+### Debug Section
+
+```bash
+# Enable debug for a section only
+debug_section() {
+    local PS4='+ ${BASH_SOURCE}:${LINENO}: '
+    set -x
+    # Problematic code here
+    "$@"
+    set +x
+}
+
+debug_section your_function arg1 arg2
+```
+
+### Trace Variable Changes
+
+```bash
+# Monitor variable assignment
+# Note: eval is used here for diagnostic purposes only.
+# Do not copy this pattern into production scripts.
+trace_var() {
+    local var_name="$1"
+    local old_value="${!var_name}"
+    local new_value="$2"
+
+    echo "[TRACE] $var_name: '$old_value' -> '$new_value'" >&2
+    eval "$var_name='$new_value'"
+}
+
+# Usage
+trace_var myvar "new value"
+```
+
+## Debugging Specific Issues
+
+### "Command not found"
+
+**Symptoms**: Script fails with `command: not found`
+
+**Checklist**:
+1. Verify command spelling
+2. Check if command exists: `which command` or `command -v command`
+3. Verify PATH: `echo $PATH`
+4. Check if alias/function shadowing: `type command`
+
+**Solution**:
+```bash
+# Use absolute path
+/usr/bin/python3 script.py
+
+# Or verify command exists first
+if ! command -v python3 >/dev/null 2>&1; then
+    echo "Error: python3 not found" >&2
+    exit 1
+fi
+```
+
+### "Unbound variable"
+
+**Symptoms**: Script fails with `unbound variable` when using `set -u`
+
+**Checklist**:
+1. Variable used before definition?
+2. Empty array causing issue?
+3. Conditional variable not set?
+
+**Solution**:
+```bash
+# Provide default value
+echo "${var:-default}"
+
+# Or allow empty
+echo "${var:-}"
+
+# Or check first
+if [[ -n "${var:-}" ]]; then
+    echo "$var"
+fi
+```
+
+### Pipeline fails silently
+
+**Symptoms**: Error in middle of pipeline doesn't cause exit
+
+**Solution**:
+```bash
+# Enable pipefail
+set -euo pipefail
+
+# Or capture pipeline status
+command1 | command2
+pipeline_status=(${PIPESTATUS[@]})
+if [[ ${pipeline_status[0]} -ne 0 ]]; then
+    echo "command1 failed" >&2
+fi
+```
+
+### Subshell loses variables
+
+**Symptoms**: Variables set in pipeline/subshell not available after
+
+**Solution**:
+```bash
+# BAD - var lost
+echo "data" | while read line; do
+    var="$line"
+done
+echo "$var"  # Empty
+
+# GOOD - var preserved
+while IFS= read -r line; do
+    var="$line"
+done < <(echo "data")
+echo "$var"  # Works
+```
+
+### Whitespace breaking arguments
+
+**Symptoms**: Filename with spaces causing errors
+
+**Solution**:
+```bash
+# BAD
+for file in *.txt; do
+    mv $file /dest/
+done
+
+# GOOD
+for file in *.txt; do
+    mv "$file" /dest/
+done
+
+# GOOD for find
+find . -name "*.txt" -print0 | while IFS= read -r -d '' file; do
+    mv "$file" /dest/
+done
+```
+
+### "Wrong branch" in && || chain
+
+**Symptoms**: The `||` fallback command runs unexpectedly, even when the initial command succeeded
+
+**Checklist**:
+1. Is there a `cmd1 && cmd2 || cmd3` pattern?
+2. Did `cmd2` fail even though `cmd1` succeeded?
+3. The `||` triggers on ANY failure in the chain, not just `cmd1`
+
+**Solution**:
+```bash
+# BAD - if cmd2 fails, cmd3 runs regardless of cmd1
+deploy && healthcheck || rollback
+
+# GOOD - use explicit if/else
+if deploy && healthcheck; then
+    echo "OK"
+else
+    rollback
+fi
+```
+
+### Numeric comparison gives wrong result
+
+**Symptoms**: A numeric comparison behaves unexpectedly (e.g., "9 is less than 7")
+
+**Checklist**:
+1. Does the comparison use `>` or `<` inside `[[ ]]`?
+2. `>` inside `[[ ]]` is lexicographic, not numeric: `"9" < "7"` as strings
+3. Does the comparison use `-gt`/`-lt` in `(( ))`? Those are wrong — `(( ))` uses `>`/`<`
+
+**Solution**:
+```bash
+# BAD - lexicographic comparison
+[[ $count > 7 ]]    # "9" is NOT greater than "7" as strings
+
+# GOOD - arithmetic context
+(( count > 7 ))
+
+# GOOD - or test operators inside [[ ]]
+[[ $count -gt 7 ]]
+```
+
+## Advanced Debugging
+
+### Custom PS4 for Better Traces
+
+```bash
+# Custom trace prompt
+export PS4='+ [${BASH_SOURCE}:${LINENO}] ${FUNCNAME[0]:-main}: '
+
+set -x
+# Your code here
+set +x
+```
+
+### Logging All Calls
+
+```bash
+# Log every function call
+declare -A call_log
+call_count() {
+    local func="${FUNCNAME[1]}"
+    ((call_log[$func]++)) || true
+    echo "Call $func: ${call_log[$func]}" >&2
+}
+
+trap 'call_count' DEBUG
+
+# ... script code ...
+
+trap - DEBUG  # Disable
+```
+
+### Timing Execution
+
+```bash
+# Time a section
+start=$(date +%s.%N)
+# ... code ...
+end=$(date +%s.%N)
+duration=$(echo "$end - $start" | bc)
+echo "Took: $duration seconds"
+```
+
+> For comprehensive performance profiling with PS4 timing, BASH_XTRACEFD, strace analysis, and benchmarking workflows, see the `shell-profiling` skill.
+
+## ShellCheck Quick Reference
+
+Common ShellCheck warnings and fixes:
+
+| SC Code | Meaning | Fix |
+|---------|---------|-----|
+| SC2086 | Double quote to prevent globbing | Use `"$var"` |
+| SC2039 | In POSIX sh | Replace bashism |
+| SC2164 | Use `cd ... || exit` | Add error handling |
+| SC2155 | Declare and assign separately (masks return value) | Declare, then assign: `local x; x="$(cmd)"` |
+| SC2002 | Useless use of cat | Pass the file directly: `grep pattern file` |
+| SC2046 | Quote to prevent word splitting | `"$(cmd)"` |
+| SC1091 | File not found | Fix path or disable |
+| SC2206 | Word splitting when filling an array | `read -ra arr <<< "$s"` or `mapfile -t arr` |
+
+Run ShellCheck:
+```bash
+shellcheck script.sh
+# Or with specific format
+shellcheck -f gcc script.sh
+# Or ignore specific rules
+shellcheck -e SC2039 script.sh
+```

package/skills/shell-profiling/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: shell-profiling
+description: Profile a slow-but-correct bash script: measure a baseline, trace with xtrace timing to find the hotspot, apply shell-specific optimisations, and benchmark the result. Use when a script works correctly but runs too slowly, or to measure/compare execution speed ("profile this script", "why is my script slow", "find the bottleneck"). For runtime errors use shell-debugging; for quality review use shell-review.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+argument-hint: [script-path]
+---
+
+# Shell Profiling Skill
+
+Guides systematic performance profiling of bash scripts to identify bottlenecks and apply targeted optimisations.
+
+## Scope
+
+This skill handles **performance problems** -- scripts that work correctly but run too slowly. It covers:
+
+- Timing measurement at multiple granularities (whole-script, per-section, per-line)
+- Xtrace-based profiling with microsecond-precision timestamps
+- Syscall and library-call analysis
+- Statistical benchmarking and comparison
+- Shell-specific optimisation patterns (subshells, builtins, I/O, loops, string processing)
+
+This skill does **not** cover:
+
+- Runtime failures or error diagnosis -- use `shell-debugging`
+- General code quality or style -- use `shell-review`
+- Writing standards or scaffolding -- use `shell-best-practices`
+
+## Workflow
+
+The profiling cycle is: **measure the original, instrument a temporary copy to diagnose, discard the copy, apply fixes to the original, benchmark the result.** Never leave profiling instrumentation in the target script.
+
+### 1. Define Target
+
+Before profiling, decide what acceptable performance looks like (e.g., "under 5 seconds" or "twice as fast"). This prevents over-optimisation and gives a clear stopping condition.
+
+### 2. Measure baseline
+
+Run the original script with `time` to establish a baseline. No modifications to the script:
+
+```bash
+time bash script.sh args
+```
+
+For per-section granularity, use `EPOCHREALTIME` inside the script (add temporarily, remove after measurement). See `references/profiling-tools.md` for all timing methods and their trade-offs.
+
+### 3. Trace with Timing
+
+Create a temporary copy of the script and add xtrace instrumentation to it. The original script remains untouched:
+
+```bash
+cp script.sh /tmp/script.profiling.sh
+```
+
+Insert after the shebang and `set` lines in the copy:
+
+```bash
+exec 42>/tmp/trace.log
+BASH_XTRACEFD=42
+PS4='+ ${EPOCHREALTIME} ${BASH_SOURCE}:${LINENO} ${FUNCNAME[0]:-main} '
+set -x
+```
+
+Run the instrumented copy, then discard it. See `references/profiling-tools.md` for BASH_XTRACEFD setup and capture patterns.
+
+### 4. Identify Hotspot
+
+Process the trace output to find the lines consuming the most time. Use `scripts/trace-aggregate.sh` for deterministic aggregation:
+
+```bash
+scripts/trace-aggregate.sh /tmp/trace.log
+```
+
+Output shows cumulative time per source location with call counts, sorted by descending time.
+
+Look for locations with the highest cumulative time and call counts, particularly tight loops, subshell invocations, or external command calls.
+
+### 5. Deep-dive
+
+When the hotspot involves system calls or I/O, use deeper analysis tools. These run against the original script without modification:
+
+```bash
+# Syscall summary (Linux)
+strace -c -f bash script.sh
+
+# Detailed resource usage
+/usr/bin/time -v bash script.sh
+```
+
+See `references/profiling-tools.md` for platform-specific alternatives (macOS: `dtruss`, `sample`, Instruments).
+
+### 6. Apply Optimisation
+
+Apply fixes to the **original script** (not the instrumented copy). Consult `references/optimisation-patterns.md` for shell-specific fixes:
+
+- Subshell elimination -- replace `$(cmd)` with parameter expansion
+- Builtin selection -- use bash builtins over external commands
+- I/O reduction -- batch reads, redirect once, avoid unnecessary pipes
+- Loop tuning -- process substitution, `lastpipe`, pre-allocated arrays
+- String processing -- single-pass awk vs multi-tool pipelines
+
+### 7. Benchmark
+
+Measure the improvement statistically against the original baseline:
+
+```bash
+# With hyperfine (recommended)
+hyperfine 'bash script_before.sh' 'bash script_after.sh'
+
+# With bench.sh (no hyperfine required)
+scripts/bench.sh -r 10 -w 1 -- bash script_before.sh
+scripts/bench.sh -r 10 -w 1 -- bash script_after.sh
+```
+
+Discard the first run (warm-up), compare median not mean.
+
+If the result still misses the target set in step 1, return to step 3 with the next hotspot; stop once the target is met or all viable patterns are exhausted.
+
+### 8. Report
+
+Present a before/after comparison:
+
+- Baseline timing vs optimised timing
+- Percentage improvement
+- Which patterns were applied
+- Any trade-offs introduced (readability, portability)
+
+Clean up temporary files (`/tmp/trace.log`, `/tmp/script.profiling.sh`).
+
+## References
+
+- `references/profiling-tools.md` -- Comprehensive catalogue of timing, tracing, syscall, and benchmarking tools with syntax examples, output interpretation, and platform availability
+- `references/optimisation-patterns.md` -- Shell-specific performance patterns with before/after code snippets, covering subshells, builtins, I/O, loops, and string processing
+
+Always read all references, scripts, and examples before producing output.
+
+## Scripts
+
+- `scripts/trace-aggregate.sh` -- Aggregates xtrace timestamps into cumulative per-line timings with call counts. Usage: `trace-aggregate.sh <trace-file> [top-n]`
+- `scripts/bench.sh` -- Manual benchmark harness with warm-up runs, median/min/max/spread statistics. Usage: `bench.sh [-r runs] [-w warmup] [--] <command...>`
+
+## Examples
+
+- `examples/profile-session.md` -- End-to-end walkthrough: profiling a slow log-processing script from baseline measurement through hotspot identification, optimisation, and benchmarking
+
+## Integration
+
+- **`shell-debugging`** -- For scripts that produce errors or incorrect output (profiling assumes the script works correctly)
+- **`shell-best-practices`** -- General writing standards, quoting, error handling (apply alongside performance optimisations)
+- **`shell-review`** -- Quality assessment after optimisation is complete
+- **`shell-architect`** agent -- Architectural decisions affecting performance (batch vs individual processing, parallelism strategy, data flow)