@objctp/opencode-shell-routines 1.2.0

package/skills/shell-profiling/references/profiling-tools.md

@@ -0,0 +1,318 @@
+# Profiling Tools Reference
+
+## Built-in Timing
+
+### `time` (bash keyword)
+
+Measures the elapsed, user, and system time for a pipeline or command.
+
+**Syntax:**
+
+```bash
+time bash script.sh
+time ( ./slow_section; ./another_section )
+```
+
+**Output fields:**
+
+| Field   | Meaning                                  |
+| ------- | ---------------------------------------- |
+| real    | Wall-clock elapsed time                  |
+| user    | CPU time spent in user mode              |
+| sys     | CPU time spent in kernel mode            |
+
+**Caveats:**
+
+- `time` is a bash reserved word, not an external command -- it works with pipelines and compound commands
+- Output goes to stderr by default; redirect with `{ time cmd; } 2>timing.log`
+- The output format varies between bash's built-in `time` and `/usr/bin/time`
+
+### `/usr/bin/time`
+
+External command providing detailed resource reporting beyond the bash built-in.
+
+**Syntax:**
+
+```bash
+# Verbose output -- page faults, context switches, peak memory
+/usr/bin/time -v bash script.sh
+
+# Custom format
+/usr/bin/time -f "Elapsed: %e s\nCPU: %P\nMax RSS: %M kB" bash script.sh
+```
+
+**Useful format specifiers:**
+
+| Specifier | Meaning                          |
+| --------- | -------------------------------- |
+| `%e`      | Elapsed real time (seconds)      |
+| `%U`      | User mode CPU time (seconds)     |
+| `%S`      | Kernel mode CPU time (seconds)   |
+| `%P`      | CPU percentage                   |
+| `%M`      | Maximum resident set size (kB)   |
+| `%W`      | Number of times swapped out      |
+| `%c`      | Voluntary context switches        |
+| `%w`      | Involuntary context switches      |
+
+**Platform:** Linux, macOS (GNU or BSD variant; format specifiers differ between them).
+
+**GNU vs BSD differences:** On macOS, the BSD variant of `/usr/bin/time` uses `-l` for verbose output (equivalent to `-v` on GNU) and supports fewer format specifiers. For consistent cross-platform behaviour, install the GNU version via `brew install coreutils` and use `gtime`.
+
+### `times` builtin
+
+Reports cumulative user and system times for the current shell and its children.
+
+```bash
+# After running some commands
+times
+# Output:
+# 0m0.012s 0m0.008s   <- shell itself
+# 0m0.345s 0m0.120s   <- children
+```
+
+Useful for measuring accumulated time across a script's lifetime. Less granular than `time`.
+
+### `$SECONDS`
+
+Integer variable that increments every second since shell start or since last assignment.
+
+```bash
+SECONDS=0
+run_expensive_operation
+echo "Took $SECONDS seconds"
+```
+
+**Precision:** Whole seconds only. Suitable for operations lasting more than a few seconds.
+
+**Portability:** Bash-specific (not POSIX).
+
+### `$EPOCHREALTIME`
+
+Microsecond-precision timestamp (seconds.microseconds since epoch). Available in bash 5.0+.
+
+```bash
+start=$EPOCHREALTIME
+run_operation
+end=$EPOCHREALTIME
+# Compute elapsed microseconds
+elapsed=$(( 10#${end%.*} * 1000000 + 10#${end#*.} - 10#${start%.*} * 1000000 - 10#${start#*.} ))
+echo "Took ${elapsed} us ($(( elapsed / 1000 )) ms)"
+```
+
+**Precision:** Microseconds. The best built-in option for sub-second measurement.
+
+**Portability:** Bash 5.0+. Not available in bash 4.x. Use `date +%s.%N` as a fallback (requires spawning an external command).
+
+---
+
+## Xtrace Profiling
+
+### PS4 with EPOCHREALTIME
+
+Configure PS4 to include a timestamp in every xtrace line:
+
+```bash
+PS4='+ ${EPOCHREALTIME} ${BASH_SOURCE}:${LINENO} ${FUNCNAME[0]:-main} '
+set -x
+```
+
+**Output format:**
+
+```
++ 1709654321.123456 script.sh:42 process_line + awk '{print $3}'
++ 1709654321.234567 script.sh:43 process_line + grep -c error
+```
+
+Each line begins with the timestamp, source file, line number, and function name.
+
+**Bash 4.x fallback** (no EPOCHREALTIME):
+
+```bash
+PS4='+ $(date +%s.%N) ${BASH_SOURCE}:${LINENO} ${FUNCNAME[0]:-main} '
+```
+
+Warning: this spawns a `date` process per trace line, adding measurable overhead. Use only for coarse analysis.
+
+### BASH_XTRACEFD
+
+Redirect xtrace output to a separate file descriptor so it does not mix with stderr:
+
+```bash
+# Open a file for trace output
+exec 42>/tmp/script.trace.log
+
+# Tell bash to write xtrace to fd 42
+BASH_XTRACEFD=42
+
+# Enable tracing (PS4 set above)
+set -x
+
+# ... script runs ...
+
+# Disable and close
+set +x
+exec 42>&-
+```
+
+**Why this matters:** Without BASH_XTRACEFD, xtrace output goes to stderr alongside actual error messages, making both harder to read. A dedicated file keeps the trace clean for post-processing.
+
+### Post-processing Trace Output
+
+Compute per-line elapsed time from the EPOCHREALTIME stamps:
+
+```bash
+# Extract timestamp, file:line, function -- compute deltas
+awk '
+BEGIN { prev = 0 }
+/^+/ {
+    ts = $2
+    delta = ts - prev
+    if (prev > 0) {
+        printf "%.6f s  %s %s\n", delta, $3, $4
+    }
+    prev = ts
+}
+' /tmp/script.trace.log | sort -rn | head -20
+```
+
+This produces a ranked list of the slowest lines, e.g.:
+
+```
+0.451234 s  script.sh:87 process_line
+0.210876 s  script.sh:45 extract_fields
+0.002345 s  script.sh:12 main
+```
+
+---
+
+## Syscall and External Analysis
+
+### `strace` (Linux)
+
+Trace system calls made by a script and its child processes.
+
+**Summary mode** -- aggregate counts and timing per syscall:
+
+```bash
+strace -c -f bash script.sh
+```
+
+Output shows calls, errors, and total time per syscall. Useful for spotting excessive `fork`, `execve`, `read`, `write`, or `stat` calls.
+
+**Per-call timing:**
+
+```bash
+strace -T -f -e trace=read,write,open,close bash script.sh 2>&1 | grep '<'
+```
+
+Each syscall line shows its duration in angle brackets: `<0.000012>`.
+
+**Filter to specific syscalls:**
+
+```bash
+strace -c -e trace=file bash script.sh    # file-related only
+strace -c -e trace=process bash script.sh  # fork/exec/clone only
+strace -c -e trace=network bash script.sh  # socket/connect only
+```
+
+**Platform:** Linux only.
+
+### `ltrace`
+
+Trace library calls (malloc, strcmp, fopen, etc.) in addition to syscalls:
+
+```bash
+ltrace -c bash script.sh
+ltrace -e malloc+free bash script.sh
+```
+
+Useful when performance problems stem from library-level operations rather than raw syscalls.
+
+**Platform:** Linux only.
+
+### `perf` (Linux)
+
+Hardware performance counters for CPU-bound analysis:
+
+```bash
+perf stat bash script.sh
+perf record -g bash script.sh
+perf report
+```
+
+Provides cache miss rates, branch mispredictions, and instruction-level profiling. Overkill for most shell scripts. Relevant when the shell invokes compiled programs doing heavy computation (e.g., image processing, numerical analysis, compression) and the bottleneck is suspected to be inside that compiled program rather than in the shell logic itself. For pure bash scripts, `strace -c` or xtrace profiling will identify bottlenecks more directly.
+
+**Platform:** Linux only.
+
+### macOS Alternatives
+
+macOS does not provide `strace`. Use these alternatives:
+
+| Tool         | Purpose                                    | Availability              |
+| ------------ | ------------------------------------------ | ------------------------- |
+| `dtruss`     | Syscall tracing (requires sudo)            | macOS built-in            |
+| `sample`     | Sampling profiler for a running process    | Xcode command-line tools  |
+| `Instruments`| GUI profiler (Time, System Trace templates)| Xcode                     |
+| `dtrace`     | D scripting language for dynamic tracing   | macOS (SIP may restrict)  |
+
+**dtruss example:**
+
+```bash
+sudo dtruss -c bash script.sh
+```
+
+---
+
+## Benchmarking
+
+### hyperfine
+
+Statistical benchmarking tool that handles warm-up runs, outlier detection, and formatting.
+
+```bash
+# Compare two versions
+hyperfine \
+    --warmup 3 \
+    --runs 10 \
+    'bash script_before.sh' \
+    'bash script_after.sh'
+
+# Export results
+hyperfine --export-markdown results.md 'bash script.sh'
+```
+
+**Key features:**
+
+- Automatic warm-up runs (discard initial slow runs caused by caching)
+- Statistical analysis (mean, median, standard deviation)
+- Outlier detection
+- Markdown/JSON/CSV export
+
+**Install:**
+
+```bash
+# macOS
+brew install hyperfine
+
+# Linux
+cargo install hyperfine
+# or: apt install hyperfine (on Debian/Ubuntu)
+```
+
+**Platform:** Cross-platform (Rust binary).
+
+### Manual Iteration-based Benchmarking
+
+When hyperfine is unavailable, use `scripts/bench.sh` — it handles warm-up runs and reports median, min, max, and spread:
+
+```bash
+scripts/bench.sh -r 10 -w 1 -- bash script.sh
+```
+
+### Statistical Considerations
+
+- **Discard the first run.** Filesystem caches and interpreter loading inflate the initial measurement.
+- **Prefer median over mean.** Outliers (background processes, I/O spikes) distort the mean; the median is more robust.
+- **Run at least 5 iterations.** Fewer than 5 makes statistical analysis unreliable. 10--20 is ideal.
+- **Control the environment.** Close other applications, disable cron jobs, and avoid running benchmarks on shared hardware.
+- **Report the spread.** Alongside the median, report min/max or standard deviation so readers can assess consistency.

package/skills/shell-profiling/scripts/bench.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# bench.sh -- Manual benchmark harness for shell scripts
+# Usage: bench.sh [-r runs] [-w warmup] [--] <command...>
+#   -r runs     Number of measured runs (default: 10)
+#   -w warmup   Number of warm-up runs to discard (default: 1)
+#   --          End option parsing; all following args form the command
+#
+# Example:
+#   bench.sh -r 15 -w 2 -- bash script.sh arg1 arg2
+#   bench.sh -- ./my-script
+
+runs=10
+warmup=1
+cmd=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+  -r)
+    runs="${2:?Missing value for -r}"
+    shift 2
+    ;;
+  -w)
+    warmup="${2:?Missing value for -w}"
+    shift 2
+    ;;
+  --)
+    shift
+    cmd=("$@")
+    break
+    ;;
+  *)
+    cmd=("$@")
+    break
+    ;;
+  esac
+done
+
+if [[ ${#cmd[@]} -eq 0 ]]; then
+  echo "Usage: $0 [-r runs] [-w warmup] [--] <command...>" >&2
+  exit 1
+fi
+
+# EPOCHREALTIME (Bash 5.0+) is required for microsecond timing
+if [[ -z "${EPOCHREALTIME:-}" ]]; then
+  echo "Error: $0 requires Bash 5.0+ (EPOCHREALTIME) for sub-second timing. Current: $(bash --version | head -1)" >&2
+  exit 1
+fi
+
+# Warm-up runs (discarded)
+for ((i = 1; i <= warmup; i++)); do
+  "${cmd[@]}" >/dev/null 2>&1 || true
+done
+
+# Measured runs
+results=()
+for ((i = 1; i <= runs; i++)); do
+  start=$EPOCHREALTIME
+  "${cmd[@]}" >/dev/null 2>&1 || true
+  end=$EPOCHREALTIME
+  elapsed=$((10#${end%.*} * 1000000 + 10#${end#*.} - 10#${start%.*} * 1000000 - 10#${start#*.}))
+  results+=("$elapsed")
+done
+
+# Compute statistics
+mapfile -t sorted < <(printf '%s\n' "${results[@]}" | sort -n)
+
+min=${sorted[0]}
+max=${sorted[-1]}
+mid=$((runs / 2))
+median=${sorted[$mid]}
+
+if [[ $((runs % 2)) -eq 0 ]]; then
+  median=$(((median + sorted[$((mid - 1))]) / 2))
+fi
+
+echo "Runs:      $runs (+ $warmup warm-up)"
+echo "Median:    $((median / 1000)) ms"
+echo "Min:       $((min / 1000)) ms"
+echo "Max:       $((max / 1000)) ms"
+echo "Spread:    $(((max - min) / 1000)) ms"

package/skills/shell-profiling/scripts/trace-aggregate.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# trace-aggregate.sh -- Aggregate xtrace timestamps into cumulative per-line timings
+# Usage: trace-aggregate.sh <trace-file> [top-n]
+# Produces a ranked list of source locations by cumulative execution time.
+#
+# Expects trace files generated with:
+#   PS4='+ ${EPOCHREALTIME} ${BASH_SOURCE}:${LINENO} ${FUNCNAME[0]:-main} '
+#   BASH_XTRACEFD=N  (redirected to the trace file)
+
+trace_file="${1:?Usage: $0 <trace-file> [top-n]}"
+top_n="${2:-20}"
+
+if [[ ! -f "$trace_file" ]]; then
+  echo "Error: trace file not found: $trace_file" >&2
+  exit 1
+fi
+
+awk '
+/^+/ {
+    ts = $2
+    if (prev > 0) {
+        delta = ts - prev
+        total[$3] += delta
+        count[$3]++
+    }
+    prev = ts
+}
+END {
+    for (loc in total)
+        printf "%.4f s  %s (called %d times)\n", total[loc], loc, count[loc]
+}
+' "$trace_file" | sort -rn | head -n "$top_n"

package/skills/shell-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: shell-review
+description: Review a working bash script for quality, correctness, standards compliance, and security, producing a structured report with severity-ranked findings and concrete fixes. Use when assessing a finished script ("review my script", "pre-merge review", "is this good bash?"). For runtime failures use shell-debugging; for deep security auditing use shell-security.
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: [file-or-diff]
+---
+
+# Shell Review Skill
+
+Produces a structured, actionable review of bash/shell scripts.
+
+**Scope**: Quality assessment of working scripts — correctness, standards, security, and style.
+
+## Target
+
+**Target:** `$ARGUMENTS`
+
+- If `$ARGUMENTS` is a file path, read that file
+- If `$ARGUMENTS` is a unified diff, extract changed lines and review them in context of the surrounding code
+- If `$ARGUMENTS` is not provided, ask for clarification
+
+## Process
+
+1. **Read the code** — understand the script's purpose before raising any issues
+2. **Run diagnostics** — ShellCheck and `bash -n` run automatically via hooks; interpret their output, don't relay it verbatim
+3. **Categorise findings** — critical (must fix), moderate (should fix), minor (nice to have); do not pad minor categories
+4. **Be specific** — every issue needs a file, line, and concrete suggested fix
+5. **Acknowledge strengths** — note what is done well; a review with no positives is usually incomplete
+
+**Done when** every finding has a file, line, and concrete fix; each passes the *when-not-to-raise* filter in `guidelines.md`; strengths are noted; severity follows the definitions in `review-template.md`; and an Overall Assessment is given.
+
+## Output
+
+Use the template in `references/review-template.md` for the exact output format. Key sections:
+
+- **Summary** — one sentence verdict
+- **Strengths** — what's done well
+- **Issues** — categorised as Critical / Moderate / Minor with file, line, issue, fix
+- **Suggestions** — anything useful that doesn't fit the issues table
+- **Security Notes** — only if genuine concerns exist
+- **Overall Assessment** — Approve / Approve with minor changes / Request changes / Needs major rework
+
+## Additional Resources
+
+### Reference Files
+
+- `references/review-template.md` — Exact output format with severity definitions
+- `references/guidelines.md` — What to raise and what not to
+
+Always read all references and examples before producing a review.
+
+### Examples
+
+- `examples/sample-review.md` — Complete review example demonstrating expected output
+
+## Integration
+
+- **`shell-security`** skill — Deep security auditing (destructive commands, credential exposure, system file risks)
+- **`shell-expert`** agent — Technical depth for complex analysis
+- **`shell-debugging`** skill — When the script has runtime failures, not quality issues
+- **`/shell-audit`** command — Comprehensive quality audit

package/skills/shell-review/examples/sample-review.md

@@ -0,0 +1,42 @@
+# Code Review: `auth.sh`
+
+## Summary
+Adds a user authentication function with input validation and basic password handling; approve pending two moderate fixes.
+
+---
+
+## [+] Strengths
+- `local` used correctly for all function-scoped variables
+- Error messages consistently directed to stderr
+- Exit codes follow conventions: 0 = success, 1 = error
+
+## [!] Issues
+
+### Moderate
+
+| File | Line | Issue | Suggested Fix |
+|------|------|-------|---------------|
+| `auth.sh` | 24 | Username accepted without pattern validation — allows injection characters | Add `[[ "$username" =~ ^[a-zA-Z0-9_]+$ ]] \|\| return 1` |
+| `auth.sh` | 31 | Missing shebang | Add `#!/usr/bin/env bash` as line 1 |
+
+### Minor
+
+| File | Line | Issue | Suggested Fix |
+|------|------|-------|---------------|
+| `auth.sh` | 18 | Single-letter variable `u` loses context at a glance | Rename to `username` |
+
+---
+
+## [*] Suggestions
+- Add rate limiting or a lockout counter for repeated failed attempts
+- Document the expected format and permissions of the password file in a comment
+- Add an audit log entry on each authentication attempt (success and failure)
+
+## [SEC] Security Notes
+- `read -s` is used for password input — correct, prevents terminal echo
+- Plain-text password comparison is high risk; consider delegating to PAM or hashing with `openssl dgst`
+- Ensure the password file is owned by root with permissions 0600
+
+---
+
+**Overall Assessment:** `Request changes`

package/skills/shell-review/references/guidelines.md

@@ -0,0 +1,48 @@
+# Code Review Guidelines
+
+## When Not to Raise an Issue
+
+Do not raise issues for:
+
+- **Style preferences** with no correctness or security implication
+- **POSIX portability concerns** when the script explicitly targets bash only (shebang is `#!/usr/bin/env bash` or `#!/bin/bash`)
+- **Performance micro-optimisations** in non-hot code paths
+- **ShellCheck false positives** like `SC2148` (missing shebang) when a shebang is clearly present
+
+## Review Quality Standards
+
+### Be Specific
+
+Every issue needs:
+- **File** — which file has the issue
+- **Line** — exact line number
+- **Issue** — clear description of what's wrong
+- **Suggested Fix** — concrete, actionable solution
+
+Vague comments like "improve error handling" are not acceptable.
+
+### Acknowledge Strengths
+
+A review with no positives is usually incomplete. Note what is done well:
+- Good error handling
+- Clear variable naming
+- Proper use of builtins
+- Security-conscious design
+- Good documentation
+
+### Categorise Appropriately
+
+Use the severity definitions in `review-template.md` (Critical / Moderate / Minor). Do not pad the minor category to appear thorough — an empty Minor section is fine.
+
+## When POSIX Portability Must Be Raised
+
+POSIX compliance is a **Critical** review dimension when the shebang is `#!/bin/sh`, `#!/usr/bin/env sh`, or `#!/usr/bin/dash`. On these scripts, bashisms will fail at runtime under dash (Ubuntu/Debian's `/bin/sh`).
+
+Raise POSIX issues when:
+- The shebang targets `sh` and the script uses bash-only features (`[[ ]]`, arrays, `${var,,}`, `<<<`, `source`, `function` keyword, etc.)
+- `checkbashisms` reports findings on a `#!/bin/sh` script
+
+Do not raise POSIX issues when:
+- The shebang explicitly targets bash (`#!/usr/bin/env bash` or `#!/bin/bash`) — bashisms are expected and correct
+
+Consult `shell-best-practices` for POSIX feature restrictions and shebang guidance.

package/skills/shell-review/references/review-template.md

@@ -0,0 +1,56 @@
+# Code Review Output Template
+
+Use this format exactly. Omit any section that has no content rather than writing "None."
+
+---
+
+# Code Review: `[filename]`
+
+## Summary
+[One sentence: what the script does and the overall verdict.]
+
+## [+] Strengths
+- [Specific thing done well, with line reference if helpful]
+
+## [!] Issues
+
+### Critical
+*Issues that cause incorrect behaviour, security vulnerabilities, or data loss.*
+
+| File | Line | Issue | Suggested Fix |
+|------|------|-------|---------------|
+| `file.sh` | 42 | Unquoted `$filename` in `rm` — word-splits on spaces | `rm -- "$filename"` |
+
+### Moderate
+*Issues that should be addressed before production use.*
+
+| File | Line | Issue | Suggested Fix |
+|------|------|-------|---------------|
+| `file.sh` | 15 | No `trap` for temp file cleanup | Add `trap 'rm -f "$tmp"' EXIT` |
+
+### Minor
+*Low-priority improvements.*
+
+| File | Line | Issue | Suggested Fix |
+|------|------|-------|---------------|
+| `file.sh` | 8 | `$i` — name gives no context | Rename to `$filename` or `$entry` |
+
+## [*] Suggestions
+[Anything useful that doesn't fit the issues table — architecture, testing gaps, missing documentation.]
+
+## [SEC] Security Notes
+[Only include if there are genuine security concerns. Do not write this section to appear thorough.]
+
+---
+
+**Overall Assessment:** `Approve` / `Approve with minor changes` / `Request changes` / `Needs major rework`
+
+---
+
+# Severity Definitions
+
+| Level | Meaning |
+|-------|---------|
+| **Critical** | Data loss, security vulnerability, incorrect output, unhandled failure mode |
+| **Moderate** | Likely to cause problems under real conditions; blocks production readiness |
+| **Minor** | Code quality, readability, or convention — no functional impact |