@objctp/opencode-shell-routines 1.2.0

package/skills/shell-batch-operations/examples/file-batch.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+#
+# Example: Batch file processing
+# Description: Find all .txt files, count lines in each, return summary statistics
+# Usage: ./file-batch.sh [directory]
+#
+# 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
+SEARCH_DIR="${1:-.}"
+MAX_SIZE="${MAX_SIZE:-10485760}" # 10MB default max file size
+
+# Process a single text file
+function process_file() {
+  local file="$1"
+  local lines
+  local size
+  local filename
+
+  filename="${file##*/}"
+  lines=$(wc -l <"$file" 2>/dev/null)
+  lines="${lines// /}"
+  size=$(wc -c <"$file" 2>/dev/null)
+  size="${size// /}"
+
+  printf '%s|%s|%s\n' "$filename" "$lines" "$size"
+}
+
+# Main processing
+function main() {
+  declare -A RESULTS
+  declare -a METADATA
+  declare -a ERRORS
+
+  # Metadata
+  batch_add_metadata METADATA "script" "$SCRIPT_NAME"
+  batch_add_metadata METADATA "search_dir" "$SEARCH_DIR"
+  batch_add_metadata METADATA "started" "$(date -Iseconds)"
+
+  batch_progress "Searching for .txt files in: ${SEARCH_DIR}"
+
+  # Variables for statistics
+  local file_count=0
+  local total_lines=0
+  local total_size=0
+  local largest_file=""
+  local largest_lines=0
+  local smallest_file=""
+  local smallest_lines=""
+  local first_file=true
+
+  # Process files
+  local temp_file
+  temp_file=$(mktemp)
+  trap 'rm -f "$temp_file"' EXIT
+
+  while IFS= read -r -d '' file; do
+    batch_progress "Found: ${file}"
+
+    # Check file size
+    local file_size
+    file_size=$(wc -c <"$file" 2>/dev/null)
+    file_size="${file_size// /}"
+
+    if ((file_size > MAX_SIZE)); then
+      batch_add_error ERRORS "File too large, skipping: ${file} (${file_size} bytes)"
+      continue
+    fi
+
+    # Process file
+    if output=$(process_file "$file"); then
+      echo "$output" >>"$temp_file"
+      ((file_count++))
+    else
+      batch_add_error ERRORS "Failed to process: ${file}"
+    fi
+  done < <(find "$SEARCH_DIR" -name "*.txt" -print0 2>/dev/null)
+
+  batch_progress "Processing statistics from ${file_count} files"
+
+  # Calculate statistics
+  while IFS='|' read -r filename lines size; do
+    total_lines=$((total_lines + lines))
+    total_size=$((total_size + size))
+
+    # Track largest/smallest
+    if ((lines > largest_lines)); then
+      largest_lines=$lines
+      largest_file="$filename"
+    fi
+
+    if $first_file || ((lines < smallest_lines)); then
+      first_file=false
+      smallest_lines=$lines
+      smallest_file="$filename"
+    fi
+  done <"$temp_file"
+
+  # Calculate averages
+  local avg_lines=0
+  local avg_size=0
+  if ((file_count > 0)); then
+    avg_lines=$((total_lines / file_count))
+    avg_size=$((total_size / file_count))
+  fi
+
+  # Store results
+  batch_add_result RESULTS "file_count" "$file_count"
+  batch_add_result RESULTS "total_lines" "$total_lines"
+  batch_add_result RESULTS "total_size" "$total_size"
+  batch_add_result RESULTS "avg_lines" "$avg_lines"
+  batch_add_result RESULTS "avg_size" "$avg_size"
+  batch_add_result RESULTS "largest_file" "$largest_file"
+  batch_add_result RESULTS "largest_lines" "$largest_lines"
+  batch_add_result RESULTS "smallest_file" "$smallest_file"
+  batch_add_result RESULTS "smallest_lines" "$smallest_lines"
+
+  # Complete metadata
+  batch_add_metadata METADATA "completed" "$(date -Iseconds)"
+
+  # Output JSON
+  batch_output RESULTS METADATA ERRORS
+}
+
+main "$@"

package/skills/shell-batch-operations/references/decision-tree.md

@@ -0,0 +1,53 @@
+# Batch vs Individual Operations Decision Tree
+
+Visual guide for deciding when to write batch scripts vs using individual tool calls.
+
+## Decision Flowchart
+
+1. **1-2 operations** → Individual calls
+2. **10+ operations** → Batch script
+3. **3-10 operations** → Evaluate:
+   - Same operation on different inputs → Batch script
+   - Different operations + interactive → Individual calls
+   - Different operations + non-interactive → Batch script
+
+## Decision Matrix
+
+| Scenario                          | Operations | Data Type | Interactive | Recommendation   |
+| --------------------------------- | ---------- | --------- | ----------- | ---------------- |
+| Count files in directory          | 1          | N/A       | No          | Individual call  |
+| Find and count lines in each .txt | 2-N        | Files     | No          | **Batch script** |
+| Debug failing deployment          | 3+         | Commands  | Yes         | Individual calls |
+| Rename 100 files by pattern       | N          | Files     | No          | **Batch script** |
+| Check service status              | 1          | N/A       | Maybe       | Individual call  |
+| Extract, transform, load data     | 3+         | Pipeline  | No          | **Batch script** |
+| Generate 10 reports               | N          | Files     | No          | **Batch script** |
+
+## Key Decision Factors
+
+### 1. Number of Operations
+
+- **1-2 operations**: Individual calls (overhead of script not worth it)
+- **3-10 operations**: Depends on other factors
+- **10+ operations**: Almost always batch
+
+### 2. Operation Similarity
+
+- **Same operation, different inputs**: Batch (file processing, bulk operations)
+- **Different operations**: Depends on complexity and interactivity
+
+### 3. Interactivity Needs
+
+- **Need to see results between steps**: Individual calls
+- **Can proceed without human input**: Batch
+- **Debugging/diagnosing**: Individual calls
+
+### 4. Token Constraints
+
+- **Constrained context**: Batch (saves up to 98.7% tokens)
+- **Plenty of context**: Either approach works
+
+### 5. Error Handling
+
+- **Operations may fail unpredictably**: Individual calls for diagnosis
+- **Predictable operations with known error modes**: Batch with error collection

package/skills/shell-best-practices/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: shell-best-practices
+description: Write secure, portable bash scripts with proper structure, error handling, and quoting. Use when scaffolding a new script ("write a bash script", "scaffold", "new shell file") or modifying, auditing, or hardening an existing one ("fix this script", "refactor bash", "add error handling to"). Covers bash functions, helpers, deployment scripts, and file operations.
+allowed-tools: Read, Write, Edit, Bash
+argument-hint: [script-name-or-path]
+---
+
+# Shell Best Practices Skill
+
+Guides Claude to write secure, portable, well-structured bash scripts — and to scaffold new scripts from the right template when starting from scratch.
+
+## When This Skill Applies
+
+- Writing or modifying any shell script
+- Creating a new bash script ("create a script", "new bash file", "scaffold", "script template")
+- Improving or auditing existing shell code
+- Writing bash functions, helpers, or libraries
+
+## Two Modes
+
+**Mode A — Modify/improve**: Apply the core standards below to the existing script at `$ARGUMENTS`.
+
+**Mode B — New script**: Select the appropriate template (see Templates section), create the file at `$ARGUMENTS` (see naming rules in Scaffolding Process), fill in the placeholders, then apply core standards.
+
+---
+
+## Core Standards
+
+Every script must include:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+- **Shebang**: `#!/usr/bin/env bash` — not `/bin/bash`
+- **Strict mode**: `set -euo pipefail` — catches unbound variables, failed commands, and pipe errors
+- **Strict mode caveat**: `set -e` does not exit on failures inside `if`/`while` conditions, `&&`/`||` chains, subshells, or negated commands. Use explicit exit-code checks or `trap ERR` for reliable error handling:
+  ```bash
+  trap 'echo "Error at line $LINENO" >&2; exit 1' ERR
+  ```
+
+### Quoting
+
+- Always quote variable expansions: `"$var"`, `"${array[@]}"`
+- Quote command substitutions: `"$(cmd)"`
+- Never leave variables unquoted in command positions
+
+### Naming Conventions
+
+- Local variables: `lower_case_with_underscores`
+- Constants and globals/exports: `UPPERCASE_WITH_UNDERSCORES`
+- Public functions: `<namespace>::function_name` — use `shroutines::` for plugin-internal scripts, or the project name (e.g. `myapp::`) for project-specific scripts
+- Private functions: `_function_name` — leading underscore signals internal use; not part of any public API
+- Use `local -r` for constants inside functions — scopes the variable and protects it. Use `readonly` for script-level constants (maximum portability). Use `declare -r` at the top level only when you need type flags (`-i`, `-a`, `-lx`). The meaningful distinction is `local -r` (scoped) vs `readonly`/`declare -r` (global):
+
+  ```bash
+  # Script-level — readonly for portability
+  SCRIPT_NAME=$(basename "$0")
+  readonly SCRIPT_NAME
+  readonly VERSION="0.1.0"
+
+  # Script-level with type flag — declare -r
+  declare -ar EXIT_CODES=(["ok"]=0 ["error"]=1 ["usage"]=2)
+
+  # Function-scoped — local -r
+  _parse_args() {
+      local -r max_retries=3
+  }
+
+  # Public function — shroutines:: namespace
+  shroutines::process_file() {
+      local input="$1"
+      # ...
+  }
+  ```
+
+### Functions
+
+> Replace the `shroutines::` prefix with the target project's namespace when scaffolding scripts for external projects.
+
+```bash
+shroutines::process_file() {
+    local input_path="$1"
+
+    if [[ ! -r "$input_path" ]]; then
+        echo "Error: cannot read file: $input_path" >&2
+        return 1
+    fi
+
+    # logic here
+
+    return 0
+}
+```
+
+- Use `local` for all function-scoped variables
+- **Separate declaration and assignment** when the value comes from a command substitution — `local` does not propagate the exit code:
+
+  ```bash
+  # BAD - $? is always 0 (exit code of 'local', not my_func)
+  local my_var="$(my_func)"
+  (( $? == 0 )) || return
+
+  # GOOD - separate lines preserve the exit code
+  local my_var
+  my_var="$(my_func)"
+  (( $? == 0 )) || return
+  ```
+
+- End functions with explicit `return 0` — makes success exit point visible and distinguishes "fell off the end" from "deliberately succeeded"
+- Use `[[ ]]` for bash tests, `[ ]` for POSIX sh
+- Errors go to stderr: `>&2`
+- Return meaningful exit codes: 0 = success, 1 = error, 2 = misuse
+
+### File Structure
+
+Every script must follow this top-to-bottom order for any sections that are present:
+
+1. **Shebang and strict mode** — `#!/usr/bin/env bash` + `set -euo pipefail`
+2. **Constants** — `readonly` / `declare -r` values that never change
+3. **Globals** — `UPPERCASE` variables with script-wide scope
+4. **Private functions** — `_function_name` helpers, internal utilities
+5. **Public functions** — `shroutines::function_name` entry points and API
+6. **Guard and execution** — `BASH_SOURCE[0]` guard + `main "$@"`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+readonly VERSION="0.1.0"
+
+VERBOSE=0
+OUTPUT_FILE=""
+
+_log_info() { printf '[INFO] %s\n' "$*" >&2; return 0; }
+
+shroutines::process() {
+  local input="$1"
+  return 0
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi
+```
+
+### Line Length
+
+- Soft limit: **120 characters** per line
+- Break long strings, pipelines, or argument lists across lines
+- Prefer `printf` over `echo` for multi-line output
+
+- **Do not use `&& ... || ...` as if/else** — if the middle command fails, the `||` branch runs even though the `&&` condition succeeded:
+
+  ```bash
+  # BAD - rollback runs if deploy succeeds but healthcheck fails
+  deploy && healthcheck || rollback
+
+  # GOOD - explicit if/else
+  if deploy && healthcheck; then
+      echo "Deploy succeeded"
+  else
+      rollback
+  fi
+  ```
+
+### Comment Conventions
+
+Only comment when the code itself cannot convey the information: a hidden constraint, a subtle invariant, a bug workaround, or behaviour that would surprise a careful reader. Write one explaining _why_ not _what_. If removing the comment wouldn't confuse a future reader, don't write it.
+
+**File header** — every script starts with one:
+
+```bash
+#!/usr/bin/env bash
+#
+# [BRIEF DESCRIPTION OF WHAT THIS SCRIPT DOES]
+# Usage: [SCRIPT_NAME] [ARGUMENTS]
+#
+```
+
+**Section dividers** — only when an individual section exceeds ~50 lines or complexity makes structure worth signposting. The standard file structure ordering is self-evident; dividers between short sections add noise. `#` tail fills to the nearest of 40, 80, or 120 columns:
+
+```bash
+###
+### :::: [description] :::: ###########
+###
+```
+
+**Public function docs** — only when the function's name and arguments don't fully convey its contract: non-obvious return codes, argument constraints, side effects, or failure conditions. Public (`shroutines::`) functions only; never on private (`_`) helpers.
+
+```bash
+# [description]
+# Arguments:
+#   $1 - [name]: [description]
+#   $2 - [name]: [description]
+# Returns:
+#   0 - [success description]
+#   1 - [failure description]
+```
+
+**Inline comments** — trailing `#` on the same line:
+
+```bash
+# GOOD — explains why
+local -r threshold=$((mem_total / 10))  # 10% of total memory
+
+# BAD — restates what
+local -r threshold=$((mem_total / 10))  # calculate threshold
+```
+
+**Annotation comments** — bare `#` line above a block:
+
+```bash
+# Track descriptors so the trap can close them even if the list changes later
+exec 3>/var/log/daemon.log
+exec 4>&1
+_OPEN_FDS+=(3 4)
+```
+
+### Security Prohibitions
+
+- **Never use `eval`** — command injection risk
+- **Never pipe to `sh` or `bash`** — injection risk
+
+For input validation, secrets handling, temp-file hygiene, and file permissions, see `references/security.md`.
+
+---
+
+## Templates (Mode B — New Scripts)
+
+Choose based on complexity and purpose:
+
+| Template             | Use When                                                                     |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `assets/standard.sh` | Most scripts — argument parsing, error handling, direct execution            |
+| `assets/minimal.sh`  | Simple one-task utilities, no complex flag parsing                           |
+| `assets/library.sh`  | Sourced by other scripts; provides reusable functions, no direct execution   |
+| `assets/posix.sh`    | POSIX sh — containers, embedded, Alpine, CI base images, maximum portability |
+
+### Template Selection Guide
+
+- Does it need `--flag` style options or multiple arguments? → **standard**
+- Is it a short utility doing one thing? → **minimal**
+- Will other scripts `source` it? → **library**
+- Must run in containers, embedded, Alpine, or under dash? → **posix**
+
+### Scaffolding Process
+
+1. Determine script name from `$ARGUMENTS` or ask the user
+2. Select template type based on purpose
+3. Create file at `$ARGUMENTS` — for directly executed scripts, omit the `.sh` extension (e.g. `deploy` not `deploy.sh`); for libraries meant to be sourced, keep the `.sh` extension (e.g. `lib-common.sh`)
+4. Copy template content and fill in placeholders:
+   - Script description
+   - Usage examples
+   - Function implementations
+5. Apply all core standards above
+6. If POSIX portability is required: use the POSIX template instead, apply `#!/bin/sh` shebang, and follow the POSIX sh Feature Restrictions below. Run `checkbashisms` to verify the final result
+
+**Done when:** the automated ShellCheck and shfmt hooks report clean on the scaffolded file — and `checkbashisms` for `#!/bin/sh` scripts. Resolve every finding before considering the script complete.
+
+---
+
+## POSIX vs Bash
+
+This plugin targets **Bash 4.4+** as its primary compatibility tier. POSIX sh is a secondary tier for maximum portability.
+
+**Rule: If the shebang says `#!/bin/sh`, the script must contain zero bashisms.** Use `#!/usr/bin/env bash` if you need bash features. The hook pipeline detects the shebang and configures ShellCheck, shfmt, and checkbashisms accordingly.
+
+### Shebang Discipline
+
+| Shebang               | Meaning                          | Tooling                                                  |
+| --------------------- | -------------------------------- | -------------------------------------------------------- |
+| `#!/usr/bin/env bash` | Bash-specific. Bashisms allowed. | shellcheck `-s bash`, shfmt `-ln bash`, `bash -n`        |
+| `#!/bin/sh`           | POSIX sh only. No bash features. | shellcheck `-s sh`, shfmt `-ln posix`, `checkbashisms`   |
+| `#!/usr/bin/dash`     | Explicit dash. Same as POSIX sh. | shellcheck `-s dash`, shfmt `-ln posix`, `checkbashisms` |
+
+### When to Choose POSIX sh
+
+Choose `#!/bin/sh` when:
+
+- The script runs in containers with minimal base images (Alpine, distroless)
+- It must execute on embedded systems or CI runners with no bash
+- It is a lightweight utility (init script, hook, wrapper) that doesn't need arrays or complex string manipulation
+
+Choose `#!/usr/bin/env bash` when:
+
+- You need arrays, associative arrays, or pattern matching with `[[ ]]`
+- The script does complex string manipulation, argument parsing, or data processing
+- It sources a library (the library template uses namerefs and associative arrays)
+
+For POSIX sh scripts, ensure no bashisms are present. Common traps: `[[ ]]`, arrays, `${var,,}`, `<<<`, `source`, `function` keyword, `echo -e`. Use `checkbashisms` to verify.
+
+When the user specifies POSIX portability, use `assets/posix.sh` instead of the bash templates.
+
+---
+
+## Reference Files
+
+- `references/patterns.md` — Argument parsing, temp files, arrays, string manipulation, parallel processing, progress output, exit code handling
+- `references/security.md` — Preventive security patterns for writing: injection prevention, input validation, temp files, signal handling
+- `${CLAUDE_PLUGIN_ROOT}/scripts/lib-common.sh` — General-purpose runtime library (logging, validation, temp files, string/array utilities), all functions `shroutines::`-namespaced. Source directly when the script can depend on the plugin being installed
+
+Always consult these reference files before producing output — both for reviewing existing scripts and scaffolding new ones.
+
+---
+
+## Integration
+
+- **`shell-security`** — Destructive commands, credential exposure, system file risks
+- **`shell-review`** — Structured quality review of a completed script
+- **`shell-architect`** agent — Multi-file project design, performance decisions, library vs executable structure
+- **Hook automation** — ShellCheck and shfmt run automatically after file creation/modification

package/skills/shell-best-practices/assets/library.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+#
+# Description: [LIBRARY NAME] - Reusable bash functions
+# Usage: source /path/to/[FILE].sh
+#
+# This file provides reusable functions for [PURPOSE]
+#
+# For general-purpose utilities (logging, validation, temp files), consider
+# sourcing the plugin runtime library instead:
+#   source "${CLAUDE_PLUGIN_ROOT}/scripts/lib-common.sh"
+#
+# Functions:
+#   shroutines::function_name - Description of what the function does
+#
+
+# Guard against direct execution
+[[ "${BASH_SOURCE[0]}" == "${0}" ]] && {
+  echo "Error: This file should be sourced, not executed" >&2
+  exit 2
+}
+
+set -euo pipefail
+
+###
+### :::: Constants :::: ###############
+###
+
+# shellcheck disable=SC2034  # template placeholder, used after scaffolding
+readonly _LIB_VERSION="0.1.0"
+
+###
+### :::: Globals :::: #################
+###
+
+# shellcheck disable=SC2034
+_LIB_TEMP_FILES=()
+
+###
+### :::: Private functions :::: #######
+###
+
+# Cleanup tracking
+function _lib_cleanup() {
+  local f
+  for f in "${_LIB_TEMP_FILES[@]+"${_LIB_TEMP_FILES[@]}"}"; do
+    rm -f "$f"
+  done
+  return 0
+}
+
+trap _lib_cleanup EXIT
+
+###
+### :::: Public functions :::: ########
+###
+
+# Validates user input against a pattern
+# Arguments:
+#   $1 - input: The string to validate
+#   $2 - pattern: Regex pattern to match (optional, defaults to alphanumeric)
+# Returns:
+#   0 - valid input
+#   1 - invalid input
+
+function shroutines::validate_input() {
+  local input="$1"
+  local pattern="${2:-^[a-zA-Z0-9_-]+$}"
+
+  [[ "$input" =~ $pattern ]]
+  return 0
+}
+
+# Log a message with timestamp and level (no subprocess)
+# Arguments:
+#   $1 - level: Log level (INFO, WARN, ERROR, DEBUG)
+#   $2 - message: The message to log
+# Returns: None
+function shroutines::log_message() {
+  printf '[%(%Y-%m-%d %H:%M:%S)T] [%s] %s\n' -1 "$1" "${*:2}" >&2
+  return 0
+}
+
+# Check if a command is available
+# Arguments:
+#   $1 - command: Name of the command to check
+# Returns:
+#   0 - command exists
+#   1 - command not found
+function shroutines::require_command() {
+  local cmd="$1"
+
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    shroutines::log_message "ERROR" "Required command not found: $cmd"
+    return 1
+  fi
+
+  return 0
+}
+
+# Ensure a directory exists, create if missing
+# Arguments:
+#   $1 - path: Directory path to ensure
+#   $2 - mode: Optional permissions (default: 0755)
+# Returns:
+#   0 - directory exists or was created
+#   1 - failed to create directory
+function shroutines::ensure_dir() {
+  local path="$1"
+  local mode="${2:-0755}"
+
+  if [[ ! -d "$path" ]]; then
+    mkdir -p "$path" || return 1
+    chmod "$mode" "$path"
+  fi
+
+  return 0
+}
+
+# Create a temporary file with automatic cleanup
+# Arguments:
+#   $1 - var_name: Name of variable to store temp file path
+# Returns:
+#   0 - temp file created successfully
+#   1 - failed to create temp file
+function shroutines::temp_file() {
+  local -n var_ref="$1"
+  local tmp
+
+  tmp=$(mktemp) || return 1
+  # shellcheck disable=SC2034  # nameref: assignment is the intended use
+  var_ref="$tmp"
+
+  _LIB_TEMP_FILES+=("$tmp")
+  return 0
+}
+
+# Export functions for use in subshells
+export -f shroutines::validate_input
+export -f shroutines::log_message
+export -f shroutines::require_command
+export -f shroutines::ensure_dir
+export -f shroutines::temp_file

package/skills/shell-best-practices/assets/minimal.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+#
+# Description: [BRIEF DESCRIPTION]
+# Usage: [SCRIPT_NAME] [ARGUMENTS]
+# shellcheck disable=SC2034
+
+set -euo pipefail
+
+###
+### :::: Constants :::: ###############
+###
+
+readonly VERSION="0.1.0"
+
+###
+### :::: Globals :::: ###############
+###
+
+INPUT=""
+
+###
+### :::: Private functions :::: ########
+###
+
+# Main logic
+function _main() {
+  local input="$1"
+
+  if [[ -z "$input" ]]; then
+    echo "Error: input required" >&2
+    exit 2
+  fi
+
+  # Process input
+  echo "Processing: $input"
+  return 0
+}
+
+###
+### :::: Public functions :::: ########
+###
+
+function shroutines::main() {
+  _main "$@"
+  return 0
+}
+
+###
+### :::: Guard and execution :::: #####
+###
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  shroutines::main "$@"
+fi