@objctp/opencode-shell-routines 1.2.0

package/scripts/lib-common.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2178
+#
+# Common library of reusable bash functions
+# Source this file in your scripts: source /path/to/lib-common.sh
+#
+# Functions:
+#   shroutines::log_info, shroutines::log_warn, shroutines::log_error, shroutines::log_debug - Logging functions
+#   shroutines::require_command - Check if a command is available
+#   shroutines::validate_input - Validate input against a pattern
+#   shroutines::ensure_dir - Create directory if it doesn't exist
+#   shroutines::temp_file, shroutines::temp_dir - Create temporary resources with cleanup
+#   shroutines::prompt_yes_no - Interactive yes/no prompt
+#   shroutines::get_timestamp - Get formatted timestamp
+#   shroutines::truncate_string - Truncate string to max length
+#
+
+# Guard against direct execution
+[[ "${BASH_SOURCE[0]}" == "${0}" ]] && {
+  echo "Error: This file should be sourced, not executed" >&2
+  exit 2
+}
+
+# Version tracking
+# shellcheck disable=SC2034  # available for consumers to check library version
+readonly LIB_COMMON_VERSION="1.0.0"
+
+###
+### :::: Logging Functions :::: #######
+###
+
+# Internal: print formatted log line (no subprocess — uses printf %()T builtin)
+# Usage: _log "LEVEL" "message"
+function _log() {
+  printf '[%(%Y-%m-%d %H:%M:%S)T] [%s] %s\n' -1 "$1" "${*:2}" >&2
+}
+
+# Log informational message
+# Usage: shroutines::log_info "message"
+function shroutines::log_info() { _log "INFO" "$@"; }
+
+# Log warning message
+# Usage: shroutines::log_warn "message"
+function shroutines::log_warn() { _log "WARN" "$@"; }
+
+# Log error message
+# Usage: shroutines::log_error "message"
+function shroutines::log_error() { _log "ERROR" "$@"; }
+
+# Log debug message (only when DEBUG=1)
+# Usage: shroutines::log_debug "message"
+function shroutines::log_debug() { [[ "${DEBUG:-0}" == "1" ]] && _log "DEBUG" "$@"; }
+
+###
+### :::: Command Validation :::: #######
+###
+
+# Check if a command is available
+# Usage: shroutines::require_command "cmdname"
+# Returns: 0 if command exists, 1 otherwise
+function shroutines::require_command() {
+  local cmd="$1"
+
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    shroutines::log_error "Required command not found: $cmd"
+    return 1
+  fi
+
+  shroutines::log_debug "Command found: $cmd"
+  return 0
+}
+
+# Require multiple commands
+# Usage: shroutines::require_commands "cmd1" "cmd2" "cmd3"
+# Returns: 0 if all commands exist, 1 otherwise
+function shroutines::require_commands() {
+  local missing=()
+
+  for cmd in "$@"; do
+    if ! command -v "$cmd" >/dev/null 2>&1; then
+      missing+=("$cmd")
+    fi
+  done
+
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    shroutines::log_error "Missing required commands: ${missing[*]}"
+    return 1
+  fi
+
+  return 0
+}
+
+###
+### :::: Input Validation :::: #######
+###
+
+# Validate input against a regex pattern
+# Usage: shroutines::validate_input "input" "pattern"
+# Returns: 0 if matches, 1 otherwise
+function shroutines::validate_input() {
+  local input="$1"
+  local pattern="${2:-^[a-zA-Z0-9_-]+$}"
+
+  [[ "$input" =~ $pattern ]]
+}
+
+# Validate a number
+# Usage: shroutines::is_number "value"
+function shroutines::is_number() {
+  local value="$1"
+  [[ "$value" =~ ^-?[0-9]+$ ]]
+}
+
+# Validate a port number (1-65535)
+# Usage: shroutines::is_port "value"
+function shroutines::is_port() {
+  local value="$1"
+  shroutines::is_number "$value" && ((value >= 1 && value <= 65535))
+}
+
+###
+### :::: File System Operations :::: #######
+###
+
+# Ensure a directory exists, create if missing
+# Usage: shroutines::ensure_dir "path" [mode]
+# Returns: 0 on success, 1 on failure
+function shroutines::ensure_dir() {
+  local path="$1"
+  local mode="${2:-0755}"
+
+  if [[ ! -d "$path" ]]; then
+    shroutines::log_debug "Creating directory: $path"
+    mkdir -p "$path" && chmod "$mode" "$path" || return 1
+  fi
+
+  return 0
+}
+
+# Create temporary file with automatic cleanup
+# Usage: shroutines::temp_file var_name
+# Tracks all temp files in _LIB_TEMP_FILES to avoid overwriting previous traps
+function shroutines::temp_file() {
+  local -n var_ref="$1"
+  local tmp
+
+  tmp=$(mktemp) || {
+    shroutines::log_error "Failed to create temporary file"
+    return 1
+  }
+
+  # shellcheck disable=SC2034  # nameref: assignment is the intended use
+  var_ref="$tmp"
+  shroutines::log_debug "Created temp file: $tmp"
+
+  _LIB_TEMP_FILES+=("$tmp")
+}
+
+# Create temporary directory with automatic cleanup
+# Usage: shroutines::temp_dir var_name
+# Tracks all temp dirs in _LIB_TEMP_DIRS to avoid overwriting previous traps
+function shroutines::temp_dir() {
+  local -n var_ref="$1"
+  local tmp
+
+  tmp=$(mktemp -d) || {
+    shroutines::log_error "Failed to create temporary directory"
+    return 1
+  }
+
+  # shellcheck disable=SC2034  # nameref: assignment is the intended use
+  var_ref="$tmp"
+  shroutines::log_debug "Created temp dir: $tmp"
+
+  _LIB_TEMP_DIRS+=("$tmp")
+}
+
+# Initialise cleanup tracking arrays and register a single trap
+# shellcheck disable=SC2034  # arrays populated by shroutines::temp_file/shroutines::temp_dir
+_LIB_TEMP_FILES=()
+_LIB_TEMP_DIRS=()
+function _lib_cleanup() {
+  local f
+  for f in "${_LIB_TEMP_FILES[@]+"${_LIB_TEMP_FILES[@]}"}"; do
+    rm -f "$f"
+  done
+  local d
+  for d in "${_LIB_TEMP_DIRS[@]+"${_LIB_TEMP_DIRS[@]}"}"; do
+    rm -rf "$d"
+  done
+}
+trap _lib_cleanup EXIT
+
+###
+### :::: User Interaction :::: ########
+###
+
+# Prompt user for yes/no confirmation
+# Usage: shroutines::prompt_yes_no "question" [default]
+# Returns: 0 for yes, 1 for no
+function shroutines::prompt_yes_no() {
+  local question="$1"
+  local default="${2:-n}"
+  local prompt
+  local response
+
+  # Build prompt string
+  if [[ "$default" == "y" ]]; then
+    prompt="$question [Y/n] "
+  else
+    prompt="$question [y/N] "
+  fi
+
+  # Read response
+  read -r -p "$prompt" response </dev/tty
+  response=${response:-$default}
+
+  # Check response
+  case "$response" in
+  [Yy] | [Yy][Ee][Ss]) return 0 ;;
+  *) return 1 ;;
+  esac
+}
+
+###
+### :::: String Utilities :::: #######
+###
+
+# Get formatted timestamp
+# Usage: shroutines::get_timestamp [format]
+# Default format: YYYY-MM-DD HH:MM:SS
+function shroutines::get_timestamp() {
+  local format="${1:-+%Y-%m-%d %H:%M:%S}"
+  date "$format"
+}
+
+# Truncate string to max length
+# Usage: shroutines::truncate_string "string" max_length [suffix]
+function shroutines::truncate_string() {
+  local string="$1"
+  local max_length="$2"
+  local suffix="${3:-...}"
+
+  if [[ ${#string} -le $max_length ]]; then
+    echo "$string"
+  else
+    printf '%.*s%s' "$((max_length - ${#suffix}))" "$string" "$suffix"
+  fi
+}
+
+# Repeat a character n times
+# Usage: shroutines::repeat_char "*" 40
+function shroutines::repeat_char() {
+  local char="$1"
+  local count="$2"
+
+  printf '%*s' "$count" '' | tr ' ' "$char"
+}
+
+###
+### :::: Array Utilities :::: #########
+###
+
+# Check if array contains a value
+# Usage: shroutines::array_contains "value" "${array[@]}"
+# Returns: 0 if found, 1 otherwise
+function shroutines::array_contains() {
+  local seek="$1"
+  shift
+
+  local item
+  for item in "$@"; do
+    [[ "$item" == "$seek" ]] && return 0
+  done
+
+  return 1
+}
+
+# Join array elements with delimiter
+# Usage: shroutines::array_join "," "${array[@]}"
+function shroutines::array_join() {
+  local delimiter="$1"
+  shift
+
+  (($# == 0)) && return 0
+
+  local first="$1"
+  shift
+
+  printf '%s' "$first"
+  local item
+  for item in "$@"; do
+    printf '%s%s' "$delimiter" "$item"
+  done
+}
+
+###
+### :::: Exit Handling :::: ###########
+###
+
+# Exit with error message
+# Usage: shroutines::die "error message" [exit_code]
+function shroutines::die() {
+  local message="$1"
+  local exit_code="${2:-1}"
+
+  shroutines::log_error "$message"
+  exit "$exit_code"
+}
+
+# Show usage and exit
+# Usage: shroutines::show_usage "usage_string"
+function shroutines::show_usage() {
+  local usage="$1"
+
+  echo "$usage" >&2
+  exit 2
+}
+
+###
+### :::: Export Functions :::: ########
+###
+
+# Export all public functions for use in subshells
+export -f _log shroutines::log_info shroutines::log_warn shroutines::log_error shroutines::log_debug
+export -f shroutines::require_command shroutines::require_commands
+export -f shroutines::validate_input shroutines::is_number shroutines::is_port
+export -f shroutines::ensure_dir shroutines::temp_file shroutines::temp_dir
+export -f shroutines::prompt_yes_no
+export -f shroutines::get_timestamp shroutines::truncate_string shroutines::repeat_char
+export -f shroutines::array_contains shroutines::array_join
+export -f shroutines::die shroutines::show_usage

package/skills/shell-batch-operations/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: shell-batch-operations
+description: Write batch shell scripts that consolidate many operations into one run emitting a single structured JSON result. Use when one action runs across 3+ similar inputs ("process all files", "rename many files") or a multi-stage shell pipeline is needed (extract → transform → aggregate), and the user need not see results between steps. Prefer this over repeated individual tool calls.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Batch Operations Skill
+
+## When to Use Batch
+
+Use batch when the user need not see results between steps — the script consolidates many operations into one JSON result. When intermediate visibility matters (debugging, per-step diagnosis), use individual tool calls instead.
+
+For the full decision matrix and borderline cases, read `references/decision-tree.md`.
+
+## The Batch Pattern
+
+All batch scripts follow this structure:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib-batch.sh"
+
+declare -A RESULTS
+declare -a METADATA
+declare -a ERRORS
+
+batch_add_metadata METADATA "script" "$(basename "$0")"
+batch_add_metadata METADATA "started" "$(date -Iseconds)"
+
+# — your processing logic here —
+
+batch_add_metadata METADATA "completed" "$(date -Iseconds)"
+batch_output RESULTS METADATA ERRORS
+```
+
+Progress goes to stderr; only the final JSON result reaches stdout.
+
+## lib-batch.sh API
+
+Sourced from `${CLAUDE_PLUGIN_ROOT}/scripts/lib-batch.sh`.
+
+| Function                                          | Purpose                                 |
+| ------------------------------------------------- | --------------------------------------- |
+| `batch_add_result RESULTS "key" "value"`          | Store a named result                    |
+| `batch_add_result_item RESULTS "item"`            | Append to a list                        |
+| `batch_add_metadata METADATA "key" "value"`       | Add run metadata                        |
+| `batch_add_error ERRORS "message"`                | Record a non-fatal error                |
+| `batch_progress "message"`                        | Log to stderr (safe during JSON output) |
+| `batch_step "label" current total`                | Log progress with percentage            |
+| `batch_output RESULTS METADATA [ERRORS]`          | Emit final JSON to stdout               |
+| `batch_process_files RESULTS METADATA ERRORS "pattern" callback` | Process files matching a glob pattern   |
+| `batch_run_command RESULTS "key" command [args]`  | Run command, store exit code and output |
+
+## Output Format
+
+```json
+{
+  "results": {
+    "file_count": 42,
+    "total_lines": 12345
+  },
+  "metadata": {
+    "script": "process-txt-files",
+    "started": "2026-03-03T10:30:00+00:00",
+    "completed": "2026-03-03T10:30:05+00:00"
+  },
+  "errors": ["File too large, skipping: ./huge.txt (50000000 bytes)"]
+}
+```
+
+The `errors` key appears only when at least one error was recorded; with none, it is omitted entirely.
+
+## Common Pitfalls
+
+| Pitfall                               | Fix                                             |
+| ------------------------------------- | ----------------------------------------------- |
+| Logging to stdout                     | Use `batch_progress` or `echo >&2`              |
+| Forgetting `batch_output`             | Always call it last with all three arrays       |
+| Non-JSON-safe values in results       | The output builder escapes them; avoid raw newlines in values |
+| Storing full file contents in results | Store summaries only                            |
+
+## Reference Files
+
+- `references/decision-tree.md` — Decision flowchart, matrix of common scenarios, and key factors (operation count, similarity, interactivity, error handling)
+- `assets/batch-template.sh` — Starting point for new batch scripts: argument parsing, lib-batch.sh sourcing with fallback, error collection scaffolding, and standard output formatting
+- `examples/file-batch.sh` — File iteration, per-file processing, and summary results
+- `examples/data-pipeline.sh` — Multi-stage pipelines (extract, transform, analyse): temp-file-based stage handoff, intermediate error handling, and percentage calculations
+
+Always read all references and examples before producing output.
+
+## Integration
+
+- **`shell-best-practices`** — Coding standards apply inside batch scripts
+- **`shell-architect`** agent — Architecture advice for complex multi-script pipelines
+- **`/shell-batch-exec`** command — Runs a batch script and parses the JSON result

package/skills/shell-batch-operations/assets/batch-template.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC1091  # dynamic source paths resolved at runtime
+#
+# Batch script template for shell-routines plugin
+# Description: [Brief description of what this batch script does]
+# Usage: ./script-name.sh [arguments]
+# Output: JSON with results, metadata, and optional errors
+#
+
+set -euo pipefail
+
+###
+### :::: CONFIGURATION :::: ###########
+###
+
+SCRIPT_NAME="${0##*/}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Source batch utilities
+# Note: CLAUDE_PLUGIN_ROOT is set by Claude Code plugin
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
+  source "${CLAUDE_PLUGIN_ROOT}/scripts/lib-batch.sh"
+elif [[ -f "${SCRIPT_DIR}/lib-batch.sh" ]]; then
+  source "${SCRIPT_DIR}/lib-batch.sh"
+else
+  echo "Error: Cannot find lib-batch.sh. Install shell-routines plugin or copy lib-batch.sh to ${SCRIPT_DIR}/" >&2
+  exit 2
+fi
+
+###
+### :::: ARGUMENT PARSING :::: ########
+###
+
+# Default values
+VERBOSE=0
+
+# shellcheck disable=SC2034  # VERBOSE is a template placeholder, used after scaffolding
+while getopts ":vh" opt; do
+  case "$opt" in
+  v) VERBOSE=1 ;;
+  h)
+    echo "Usage: $SCRIPT_NAME [options]"
+    echo "Options:"
+    echo "  -v    Verbose output"
+    echo "  -h    Show this help"
+    exit 0
+    ;;
+  \?)
+    echo "Invalid option: -$OPTARG" >&2
+    exit 2
+    ;;
+  esac
+done
+
+shift $((OPTIND - 1))
+
+###
+### :::: FUNCTIONS :::: ###############
+###
+
+# Process a single item
+# Usage: process_item "item"
+# Returns: 0 on success, 1 on failure
+process_item() {
+  local item="$1"
+
+  # Your processing logic here
+  batch_progress "Processing: ${item}"
+
+  return 0
+}
+
+# Main processing function
+# Usage: main
+main() {
+  # Results storage
+  # shellcheck disable=SC2034  # passed by nameref to lib-batch.sh functions
+  declare -A RESULTS
+  # shellcheck disable=SC2034
+  declare -a METADATA
+  # shellcheck disable=SC2034
+  declare -a ERRORS
+
+  # Add metadata
+  batch_add_metadata METADATA "script" "$SCRIPT_NAME"
+  batch_add_metadata METADATA "started" "$(date -Iseconds)"
+
+  ###
+  ### :::: YOUR LOGIC HERE :::: ########
+  ###
+
+  batch_progress "Starting batch processing"
+
+  # Capture total before processing loop
+  local total=$#
+
+  # Example: Process items
+  local count=0
+  for item in "$@"; do
+    if process_item "$item"; then
+      count=$((count + 1))
+    else
+      batch_add_error ERRORS "Failed to process: ${item}"
+    fi
+  done
+
+  # Add summary results
+  batch_add_result RESULTS "total" "$total"
+  batch_add_result RESULTS "processed" "$count"
+  batch_add_result RESULTS "failed" "$(($# - count))"
+
+  ###
+  ### :::: OUTPUT RESULTS :::: #########
+  ###
+
+  batch_add_metadata METADATA "completed" "$(date -Iseconds)"
+  batch_output RESULTS METADATA ERRORS
+}
+
+###
+### :::: ENTRY POINT :::: #############
+###
+
+main "$@"

package/skills/shell-batch-operations/examples/data-pipeline.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Example: Multi-stage data pipeline
+# Description: Extract log entries, transform them, aggregate by status code
+# Usage: ./data-pipeline.sh [log_file]
+#
+# shellcheck disable=SC1091  # dynamic source paths resolved at runtime
+# shellcheck disable=SC2034
+
+set -euo pipefail
+
+SCRIPT_NAME="${0##*/}"
+
+# Source batch utilities
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
+  source "${CLAUDE_PLUGIN_ROOT}/scripts/lib-batch.sh"
+elif [[ -f "$(dirname "$0")/../../scripts/lib-batch.sh" ]]; then
+  source "$(dirname "$0")/../../scripts/lib-batch.sh"
+else
+  echo "Error: Cannot find lib-batch.sh" >&2
+  exit 2
+fi
+
+# Configuration
+LOG_FILE="${1:-access.log}"
+STATUS_PATTERN="${STATUS_PATTERN:-'^[0-9]{3}$'}"
+
+# Stage 1: Extract status codes from log file
+# Assumes Combined Log Format or similar
+function stage1_extract() {
+  local log_file="$1"
+
+  batch_progress "Stage 1: Extracting status codes from ${log_file}"
+
+  if [[ ! -r "$log_file" ]]; then
+    batch_add_error ERRORS "Cannot read log file: ${log_file}"
+    return 1
+  fi
+
+  # Extract status codes (assumes standard log format with status at position 9)
+  awk '{print $9}' "$log_file" | grep -E "$STATUS_PATTERN" || true
+}
+
+# Stage 2: Transform and count status codes
+function stage2_transform() {
+  batch_progress "Stage 2: Aggregating status codes"
+
+  local -A status_counts
+  local count=0
+
+  while IFS= read -r status; do
+    if [[ -n "$status" ]]; then
+      status_counts["$status"]=$((${status_counts["$status"]:-0} + 1))
+      count=$((count + 1))
+    fi
+  done
+
+  # Output results
+  for status in "${!status_counts[@]}"; do
+    printf '%s|%s\n' "$status" "${status_counts[$status]}"
+  done | sort -t '|' -k2 -nr
+}
+
+# Stage 3: Calculate statistics
+function stage3_analyze() {
+  batch_progress "Stage 3: Calculating statistics"
+
+  local total_requests=0
+  local success_requests=0
+  local redirect_requests=0
+  local error_requests=0
+
+  while IFS='|' read -r status count; do
+    total_requests=$((total_requests + count))
+
+    case "$status" in
+    2*)
+      success_requests=$((success_requests + count))
+      ;;
+    3*)
+      redirect_requests=$((redirect_requests + count))
+      ;;
+    4* | 5*)
+      error_requests=$((error_requests + count))
+      ;;
+    esac
+  done
+
+  printf '%s|%s|%s|%s\n' "$total_requests" "$success_requests" "$redirect_requests" "$error_requests"
+}
+
+# Main processing pipeline
+function main() {
+  declare -A RESULTS
+  declare -a METADATA
+  declare -a ERRORS
+
+  # Metadata
+  batch_add_metadata METADATA "script" "$SCRIPT_NAME"
+  batch_add_metadata METADATA "log_file" "$LOG_FILE"
+  batch_add_metadata METADATA "started" "$(date -Iseconds)"
+
+  local temp_extract
+  local temp_transform
+  temp_extract=$(mktemp)
+  temp_transform=$(mktemp)
+  trap 'rm -f "$temp_extract" "$temp_transform"' EXIT
+
+  # STAGE 1: Extract
+  if ! stage1_extract "$LOG_FILE" >"$temp_extract"; then
+    batch_add_metadata METADATA "completed" "$(date -Iseconds)"
+    batch_add_result RESULTS "success" "false"
+    batch_output RESULTS METADATA ERRORS
+    return 1
+  fi
+
+  local extracted_count
+  extracted_count=$(wc -l <"$temp_extract")
+  batch_add_result RESULTS "extracted_entries" "$extracted_count"
+
+  # STAGE 2: Transform
+  stage2_transform <"$temp_extract" >"$temp_transform"
+
+  # Store top status codes
+  local index=0
+  while IFS='|' read -r status count && ((index < 10)); do
+    batch_add_result RESULTS "status_${status}" "$count"
+    index=$((index + 1))
+  done <"$temp_transform"
+
+  # STAGE 3: Analyze
+  while IFS='|' read -r total success redirect error; do
+    batch_add_result RESULTS "total_requests" "$total"
+    batch_add_result RESULTS "success_requests" "$success"
+    batch_add_result RESULTS "redirect_requests" "$redirect"
+    batch_add_result RESULTS "error_requests" "$error"
+
+    # Calculate percentages
+    if ((total > 0)); then
+      local success_pct=$((success * 100 / total))
+      local redirect_pct=$((redirect * 100 / total))
+      local error_pct=$((error * 100 / total))
+
+      batch_add_result RESULTS "success_percent" "$success_pct"
+      batch_add_result RESULTS "redirect_percent" "$redirect_pct"
+      batch_add_result RESULTS "error_percent" "$error_pct"
+    fi
+  done < <(stage3_analyze <"$temp_transform")
+
+  # Complete metadata
+  batch_add_metadata METADATA "completed" "$(date -Iseconds)"
+  batch_add_result RESULTS "success" "true"
+
+  # Output JSON
+  batch_output RESULTS METADATA ERRORS
+}
+
+main "$@"