mainframe-bash

name	mainframe-bash
description	Use when writing bash scripts, shell automation, CLI tools, or any bash programming task with OpenCode.

OpenCode - Mainframe Integration

Instructions for using Mainframe (3,821+ pure bash functions) with OpenCode AI coding assistant.

Overview

Mainframe provides 3,821+ pure bash functions across 152 libraries with zero external dependencies. Integrate with OpenCode for high-performance bash scripting without external tool dependencies.

Installation

# Clone Mainframe to default location
git clone https://github.com/gtwatts/mainframe.git ~/.mainframe

# Set environment variable
export MAINFRAME_ROOT="$HOME/.mainframe"

Configuration

OpenCode Configuration File Location

OpenCode typically uses configuration files in the following locations:

• Project-level: .opencode/config or opencode.json in project root
• User-level: ~/.opencode/config or ~/.config/opencode/config
• Environment: via OPENCODE_CONFIG variable

Setting Up Mainframe Integration

Add to your OpenCode configuration:

{
  "environment": {
    "MAINFRAME_ROOT": "$HOME/.mainframe",
    "PATH": "$HOME/.mainframe/bin:$PATH"
  },
  "preamble": "When writing bash scripts, always source Mainframe first:\nsource \"${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh\"\n\nMainframe provides 3,821+ pure bash functions. Use instead of jq, sed, awk."
}

Or in YAML format (if supported):

environment:
  MAINFRAME_ROOT: "$HOME/.mainframe"
  PATH: "$HOME/.mainframe/bin:$PATH"

preamble: |
  When writing bash scripts, always source Mainframe first:
  source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"
  
  Mainframe provides 3,821+ pure bash functions across 152 libraries.
  Use Mainframe functions instead of external tools like jq, sed, awk.

Shell Environment Setup

Add to your shell profile for OpenCode to inherit:

# ~/.bashrc or ~/.zshrc
export MAINFRAME_ROOT="$HOME/.mainframe"
export PATH="$MAINFRAME_ROOT/bin:$PATH"

Mainframe Loading Instructions

Script Template

Every bash script generated by OpenCode should start with:

#!/usr/bin/env bash
source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"

# Your script logic here

Pre-Prompt Integration

When starting an OpenCode session, include in your prompt:

When generating bash scripts:
1. ALWAYS start with: source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"
2. Use Mainframe functions for all operations (JSON, strings, arrays, files)
3. Never spawn jq, sed, awk, or cat - use pure bash equivalents
4. Reference: ~/.mainframe/CHEATSHEET.md

Verification Check

Include this check at the start of complex scripts:

#!/usr/bin/env bash

# Verify Mainframe is available
if [[ ! -f "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh" ]]; then
    echo "Error: Mainframe not found. Install with:"
    echo "  git clone https://github.com/gtwatts/mainframe.git ~/.mainframe"
    exit 1
fi

source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"

Core Functions Reference

JSON Operations (No jq Required)

# Create JSON objects
json_object "name=John" "age:number=30" "active:bool=true"
# Output: {"name":"John","age":30,"active":true}

# Create arrays
json_array "apple" "banana" "cherry"
json_array_typed number 1 2 3

# Query JSON
json_get '{"name":"John","age":30}' "name"   # "John"
json_keys '{"a":1,"b":2}'                     # "a b"
json_merge '{"a":1}' '{"b":2}'               # {"a":1,"b":2}

# Validation
json_valid '{"a":1}'                          # returns 0 if valid
json_pretty '{"a":1,"b":2}'                   # formatted

String Manipulation

trim_string "  hello  "           # "hello"
to_lower "HELLO"                  # "hello"
to_upper "hello"                  # "HELLO"
replace_all "foo bar foo" "foo" "baz"  # "baz bar baz"
split_string "a,b,c" ","         # outputs a\nb\nc
contains "hello" "ell"            # returns 0 (true)
starts_with "hello" "hel"         # returns 0
ends_with "hello" "lo"            # returns 0
capitalize "hello world"          # "Hello world"

Array Operations

arr=(5 3 1 4 2)
array_length "${arr[@]}"          # 5
array_sort "${arr[@]}"            # "1 2 3 4 5"
array_unique 1 2 2 3 3            # "1 2 3"
array_join ", " "${arr[@]}"       # "5, 3, 1, 4, 2"
array_contains "3" "${arr[@]}"    # returns 0
array_filter "is_int" "${arr[@]}" # filter by predicate

Validation & Security

# Format validation
validate_email "[e-mail]"
validate_url "https://example.com"
validate_ipv4 "192.168.1.1"
validate_json '{"a":1}'
validate_path_safe "$user_path" "/allowed/base"

# Sanitization
sanitize_shell_arg "$user_input"
sanitize_filename "a/b<c>.txt"    # "a_b_c_.txt"
sanitize_html "<script>alert(1)"  # "&lt;script&gt;alert(1)"
sanitize_json 'say "hi"'         # 'say \"hi\"'

File Operations

read_file "$path"                 # file contents
file_write "$path" "content"      # atomic write
file_append "$path" "more"        # append to file
file_exists "$path"               # returns 0/1
dir_exists "/tmp"                 # returns 0/1
file_head "$path" 10              # first 10 lines
file_tail "$path" 5               # last 5 lines
file_lines "$path"                # line count
file_size "$path"                 # bytes

Path Manipulation

path_join "/base" "sub" "file"    # "/base/sub/file"
path_dir "/foo/bar/file.txt"      # "/foo/bar"
path_base "/foo/bar/file.txt"     # "file.txt"
path_ext "/foo/bar.tar.gz"        # "gz"
path_normalize "/foo//bar/../baz" # "/foo/baz"
path_is_safe "/allowed" "$user_path"  # prevents traversal

Git Operations

git_branch                        # current branch
git_is_dirty                      # returns 0 if uncommitted changes
git_files_changed                 # list of modified files
git_commit_hash                   # short hash
git_commit_message                # latest commit message
git_summary                       # "main @ abc1234 [clean]"
git_log_oneline 5                 # last 5 commits

HTTP Requests

http_get "http://api.example.com/data"
http_post "http://api.example.com" '{"name":"test"}'
http_put "http://api.example.com/1" '{"name":"updated"}'
http_delete "http://api.example.com/1"
http_status                       # last response status
http_body                         # last response body
http_is_success                   # returns 0 for 2xx

Agent Working Memory (AWM)

# Session management
sid=$(awm_init "opencode-session")
awm_resume "$sid"
awm_close

# Checkpoint data
awm_checkpoint "step" "5"
awm_checkpoint "files" "a.txt,b.txt"
awm_progress "task" "50%"

# Retrieve data
value=$(awm_get "step" "0")
entries=$(awm_recent "logs" 10)

Multi-Agent IPC

# Registration
agent_register "opencode-1" code.analyze typescript

# Discovery
agents=$(agent_discover "code.analyze")

# Messaging
agent_send "claude-1" '{"task":"review"}'
response=$(agent_receive 30)

# Work queues
agent_work_queue "tasks"
agent_work_push "tasks" '{"file":"main.ts"}'
item=$(agent_work_pop "tasks")

Pre-Prompt Integration

For OpenCode Configuration

Add this to your OpenCode system prompt or configuration:

## Mainframe Integration

When working with bash scripts in OpenCode:

1. **ALWAYS source Mainframe at the start of every script:**
   ```bash
   source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"

2. Use Mainframe functions instead of external tools:

   • Use json_object, json_get instead of jq
   • Use replace_all, trim_string instead of sed
   • Use array_join, array_sort instead of awk
   • Use read_file instead of cat

3. Performance benefits:

   • 20-72x faster than spawning external processes
   • Zero dependencies (pure bash)
   • Atomic operations for file safety

4. Security features:

   • validate_path_safe prevents directory traversal
   • sanitize_shell_arg prevents injection
   • sanitize_filename creates safe filenames

5. Multi-agent support:

   • Use agent_register to register capabilities
   • Use agent_discover to find other agents
   • Use agent_send/agent_receive for messaging

6. Reference:

   • Full docs: ~/.mainframe/CHEATSHEET.md
   • Function index: ~/.mainframe/FUNCTIONS.json
   • Decision trees: ~/.mainframe/DECISION_TREES.md

### Quick Reference Card

```bash
# Most commonly used functions

# JSON
json_object "key=value" "num:number=42"
json_get '{"a":1}' "a"
json_array "a" "b" "c"

# Strings
trim_string "  text  "
to_lower "HELLO"
replace_all "foo" "o" "a"

# Arrays
array_join ", " "${arr[@]}"
array_sort "${arr[@]}"
array_contains "x" "${arr[@]}"

# Files
read_file "$path"
file_write "$path" "content"
path_join "/base" "file.txt"

# Validation
validate_email "$email"
validate_path_safe "$path" "/allowed"
sanitize_shell_arg "$input"

# Git
git_branch
git_is_dirty
git_files_changed

Example Scripts

Example 1: Configuration Manager

#!/usr/bin/env bash
source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"

config_file="${1:-config.json}"

# Validate input
validate_path_safe "$config_file" "$(pwd)" || die 1 "Invalid path"

# Read or create config
if file_exists "$config_file"; then
    config=$(read_file "$config_file")
    log_info "Loaded existing config"
else
    config=$(json_object \
        "version=1.0" \
        "created=$(now_iso)" \
        "settings:raw={}")
    log_info "Created new config"
fi

# Update settings
new_config=$(json_merge "$config" \
    "$(json_object \
        "last_modified=$(now_iso)" \
        "editor=opencode")")

# Write atomically
file_write "$config_file" "$(json_pretty "$new_config")"
success "Config updated"

Example 2: Log Analyzer

#!/usr/bin/env bash
source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"

log_file="$1"
[[ -z "$log_file" ]] && die 1 "Usage: $0 <log-file>"

# Count error types
errors=$(file_grep "$log_file" "ERROR" | wc -l)
warnings=$(file_grep "$log_file" "WARN" | wc -l)

# Extract unique error messages
unique_errors=$(file_grep "$log_file" "ERROR" | \
    sed 's/.*ERROR: //' | sort -u)

# Output report
json_object \
    "file=$(path_base "$log_file")" \
    "errors:number=$errors" \
    "warnings:number=$warnings" \
    "unique_errors:number=$(echo "$unique_errors" | wc -l)" \
    "analyzed_at=$(now_iso)"

Example 3: Multi-Agent Task Coordinator

#!/usr/bin/env bash
source "${MAINFRAME_ROOT:-$HOME/.mainframe}/lib/common.sh"

# Initialize
session=$(awm_init "opencode-coordinator")
agent_register "opencode-coord" task.distribute

# Get files to process
files=($(find . -name "*.ts" -not -path "*/node_modules/*"))
log_info "Distributing ${#files[@]} files"

# Create work queue
agent_work_queue "typescript-analysis"
for file in "${files[@]}"; do
    agent_work_push "typescript-analysis" \
        "$(json_object "file=$file" "session=$session")"
done

# Notify workers
agent_broadcast "$(json_object \
    "event=work_available" \
    "queue=typescript-analysis" \
    "count:number=${#files[@]}")"

# Wait for completion
awm_checkpoint "status" "waiting"
log_info "Waiting for workers to complete..."

OpenCode Specific Notes

1. Configuration: OpenCode may support different config formats (JSON, YAML) - adapt accordingly
2. Environment: Variables set in OpenCode config are inherited by spawned processes
3. Project vs Global: Can configure Mainframe per-project or globally
4. State Persistence: Use AWM for long-running tasks that span multiple OpenCode sessions

Quick Reference Commands

mainframe quickref                    # List all functions
mainframe quickref json               # JSON functions only  
mainframe quickref string             # String functions only
mainframe quickref --search "array"   # Search for array functions

Reference Files

• ~/.mainframe/CHEATSHEET.md - All 3,821+ function signatures
• ~/.mainframe/FUNCTIONS.json - Machine-readable function index
• ~/.mainframe/DECISION_TREES.md - "I need X" workflow guidance
• ~/.mainframe/docs/ORCHESTRATION.md - Multi-agent coordination

Repository

• Source: https://github.com/gtwatts/mainframe
• Install: git clone https://github.com/gtwatts/mainframe.git ~/.mainframe
• License: MIT