@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/bash/README.md

@@ -0,0 +1,196 @@
+# Bash Coding Standards
+
+Comprehensive Bash coding standards for professional, maintainable, and secure Bash scripts.
+
+## Overview
+
+This module provides AI-driven guidance for writing high-quality Bash scripts across diverse project types. It includes universal best practices that apply to all Bash code, plus category-specific rules for automation, CI/CD, CLI tools, configuration, data processing, system administration, and cross-platform development.
+
+## Installation
+
+### With CLI (Future)
+```bash
+augx link coding-standards/bash
+```
+
+### Manual Setup
+1. Copy this module to your project's `.augment/` folder
+2. Create `.augment/bash-config.json` to configure categories
+3. Reference rules in your project documentation
+
+## Directory Structure
+
+```
+augment-extensions/coding-standards/bash/
+├── module.json                          # Module metadata
+├── README.md                            # This file
+├── rules/
+│   ├── universal-standards.md          # Cross-cutting standards
+│   ├── naming-conventions.md           # Variables, functions, constants
+│   ├── error-handling.md               # set -euo pipefail, traps
+│   ├── security-practices.md           # Input sanitization, injection prevention
+│   ├── performance-optimization.md     # Subshells, loops, pipes
+│   ├── testing-guidelines.md           # Bats, shunit2 integration
+│   ├── automation-scripts.md           # Category: Automation
+│   ├── cicd-pipelines.md               # Category: CI/CD
+│   ├── cli-tools.md                    # Category: Command-line tools
+│   ├── configuration-files.md          # Category: Configuration
+│   ├── data-processing.md              # Category: Data processing
+│   ├── system-administration.md        # Category: System administration
+│   └── cross-platform.md               # Category: Cross-platform
+└── examples/
+    ├── automation-example.sh
+    ├── cicd-example.sh
+    ├── cli-example.sh
+    ├── config-example.sh
+    ├── data-processing-example.sh
+    ├── sysadmin-example.sh
+    └── cross-platform-example.sh
+```
+
+## Core Guidelines
+
+### Universal Standards
+- **Shebang**: `#!/usr/bin/env bash` (portable) or `#!/bin/bash` (system-specific)
+- **Strict Mode**: `set -euo pipefail` (exit on error, undefined variables, pipe failures)
+- **Quoting**: Always quote variables: `"$var"` not `$var`
+- **Functions**: Modularize code into functions
+- **Error Handling**: Use traps for cleanup, check exit codes
+- **Logging**: Include timestamps and severity levels
+
+### Naming Conventions
+```bash
+# Variables: lowercase with underscores
+user_name="john"
+file_path="/tmp/data.txt"
+
+# Constants: UPPERCASE with underscores
+readonly MAX_RETRIES=3
+readonly API_URL="https://api.example.com"
+
+# Functions: lowercase with underscores
+function process_data() {
+    local input="$1"
+    # ...
+}
+```
+
+### Error Handling
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Trap for cleanup
+trap 'cleanup' EXIT ERR
+
+function cleanup() {
+    rm -f "$temp_file"
+}
+
+# Check command success
+if ! command -v jq &> /dev/null; then
+    echo "Error: jq is required" >&2
+    exit 1
+fi
+```
+
+### Security
+```bash
+# Input validation
+if [[ ! "$user_input" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    echo "Error: Invalid input" >&2
+    exit 1
+fi
+
+# Avoid command injection
+# ❌ Bad: eval "ls $user_input"
+# ✅ Good: Use arrays and proper quoting
+files=("$user_input"/*.txt)
+```
+
+## Configuration
+
+Create `.augment/bash-config.json`:
+
+```json
+{
+  "bash_categories": ["automation", "cicd"],
+  "bash_version": "4.0",
+  "strict_mode": true,
+  "static_analysis": {
+    "tool": "shellcheck",
+    "severity": "warning"
+  },
+  "testing": {
+    "framework": "bats",
+    "version": "1.x"
+  },
+  "posix_compliance": false
+}
+```
+
+## Categories
+
+### Automation Scripts
+- Idempotency patterns
+- Dry-run mode
+- Task scheduling integration
+- Atomic operations
+
+### CI/CD Pipelines
+- Environment variable validation
+- Secret management
+- Debugging with `set -x`
+- Rollback on failure
+
+### CLI Tools
+- Argument parsing with `getopts`
+- Help output formatting
+- Exit status management
+- Input validation
+
+### Configuration Files
+- Sourcing mechanisms
+- Conditional loading
+- Alias and function definitions
+- No side effects
+
+### Data Processing
+- Stream processing for large files
+- awk, sed, grep patterns
+- Special character escaping
+- Memory-efficient operations
+
+### System Administration
+- Privilege checks
+- User/group management
+- Service control
+- Logging and auditing
+
+### Cross-Platform
+- OS detection
+- Portable command usage
+- Path handling differences
+- Fallback mechanisms
+
+## Character Count
+
+**Total**: ~TBD characters
+
+## Contents
+
+- 6 universal rule files
+- 7 category-specific rule files
+- 7 code examples
+- Configuration schema
+- shellcheck integration guide
+- Bats testing framework guide
+
+## References
+
+- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
+- [Bash Pitfalls](https://mywiki.wooledge.org/BashPitfalls)
+- [OWASP Shell Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html)
+- [shellcheck](https://www.shellcheck.net/)
+- [Bats](https://github.com/bats-core/bats-core)
+

package/augment-extensions/coding-standards/bash/module.json

@@ -0,0 +1,163 @@
+{
+  "name": "bash-standards",
+  "version": "1.0.0",
+  "displayName": "Bash Coding Standards",
+  "description": "Comprehensive Bash coding standards for professional, maintainable, and secure Bash scripts across automation, CI/CD, CLI tools, configuration, data processing, system administration, and cross-platform development.",
+  "type": "coding-standards",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "keywords": [
+    "bash",
+    "shell",
+    "coding-standards",
+    "automation",
+    "cicd",
+    "cli",
+    "shellcheck",
+    "bats",
+    "security",
+    "performance",
+    "cross-platform"
+  ],
+  "augment": {
+    "characterCount": 0,
+    "priority": "high",
+    "category": "coding-standards",
+    "language": "bash",
+    "tags": ["bash", "shell-scripting", "automation", "devops"],
+    "categories": {
+      "automation": {
+        "description": "Automation scripts (backups, scheduled tasks)",
+        "rules": ["automation-scripts.md"],
+        "examples": ["automation-example.sh"]
+      },
+      "cicd": {
+        "description": "CI/CD pipeline scripts",
+        "rules": ["cicd-pipelines.md"],
+        "examples": ["cicd-example.sh"]
+      },
+      "cli": {
+        "description": "Command-line tools and utilities",
+        "rules": ["cli-tools.md"],
+        "examples": ["cli-example.sh"]
+      },
+      "config": {
+        "description": "Configuration files (.bashrc, .profile)",
+        "rules": ["configuration-files.md"],
+        "examples": ["config-example.sh"]
+      },
+      "data": {
+        "description": "Data processing scripts",
+        "rules": ["data-processing.md"],
+        "examples": ["data-processing-example.sh"]
+      },
+      "sysadmin": {
+        "description": "System administration tasks",
+        "rules": ["system-administration.md"],
+        "examples": ["sysadmin-example.sh"]
+      },
+      "crossplatform": {
+        "description": "Cross-platform scripts (macOS, Linux)",
+        "rules": ["cross-platform.md"],
+        "examples": ["cross-platform-example.sh"]
+      }
+    },
+    "universalRules": [
+      "universal-standards.md",
+      "naming-conventions.md",
+      "error-handling.md",
+      "security-practices.md",
+      "performance-optimization.md",
+      "testing-guidelines.md"
+    ]
+  },
+  "installation": {
+    "required": false,
+    "instructions": "This module is automatically loaded when working with Bash files. Configure categories in .augment/bash-config.json"
+  },
+  "configuration": {
+    "file": ".augment/bash-config.json",
+    "schema": {
+      "bash_categories": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["automation", "cicd", "cli", "config", "data", "sysadmin", "crossplatform"]
+        },
+        "description": "Project categories to apply"
+      },
+      "bash_version": {
+        "type": "string",
+        "description": "Minimum Bash version",
+        "default": "4.0"
+      },
+      "strict_mode": {
+        "type": "boolean",
+        "description": "Enforce set -euo pipefail",
+        "default": true
+      },
+      "static_analysis": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string",
+            "enum": ["shellcheck"]
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["error", "warning", "info", "style"]
+          }
+        }
+      },
+      "testing": {
+        "type": "object",
+        "properties": {
+          "framework": {
+            "type": "string",
+            "enum": ["bats", "shunit2"]
+          },
+          "version": {
+            "type": "string",
+            "default": "1.x"
+          }
+        }
+      },
+      "posix_compliance": {
+        "type": "boolean",
+        "description": "Enforce POSIX compliance",
+        "default": false
+      }
+    }
+  },
+  "dependencies": {
+    "external": {
+      "shellcheck": ">=0.8.0",
+      "bats": ">=1.0.0"
+    }
+  },
+  "contents": [
+    "module.json",
+    "README.md",
+    "rules/universal-standards.md",
+    "rules/naming-conventions.md",
+    "rules/error-handling.md",
+    "rules/security-practices.md",
+    "rules/performance-optimization.md",
+    "rules/testing-guidelines.md",
+    "rules/automation-scripts.md",
+    "rules/cicd-pipelines.md",
+    "rules/cli-tools.md",
+    "rules/configuration-files.md",
+    "rules/data-processing.md",
+    "rules/system-administration.md",
+    "rules/cross-platform.md",
+    "examples/automation-example.sh",
+    "examples/cicd-example.sh",
+    "examples/cli-example.sh",
+    "examples/config-example.sh",
+    "examples/data-processing-example.sh",
+    "examples/sysadmin-example.sh",
+    "examples/cross-platform-example.sh"
+  ]
+}
+

package/augment-extensions/coding-standards/bash/rules/naming-conventions.md

@@ -0,0 +1,336 @@
+# Bash Naming Conventions
+
+Comprehensive naming standards for Bash code following Google Shell Style Guide and industry best practices.
+
+## Variables
+
+### Standard Variables
+
+**Use lowercase with underscores** (snake_case):
+
+```bash
+# ✅ Correct
+user_name="john_doe"
+file_path="/tmp/data.txt"
+max_retry_count=3
+is_enabled=true
+
+# ❌ Incorrect
+userName="john_doe"        # camelCase
+file-path="/tmp/data.txt"  # kebab-case
+MAXRETRYCOUNT=3            # ALL CAPS (reserved for constants)
+```
+
+### Constants and Environment Variables
+
+**Use UPPERCASE with underscores**:
+
+```bash
+# Constants
+readonly MAX_RETRIES=5
+readonly DEFAULT_TIMEOUT=30
+readonly API_BASE_URL="https://api.example.com"
+
+# Environment variables
+export PATH="/usr/local/bin:$PATH"
+export DATABASE_URL="postgresql://localhost/mydb"
+export LOG_LEVEL="INFO"
+```
+
+### Boolean Variables
+
+Prefix with `is_`, `has_`, `should_`, `can_`:
+
+```bash
+is_valid=true
+has_permission=false
+should_continue=true
+can_write=false
+
+# Usage in conditionals
+if [[ "$is_valid" == "true" ]]; then
+  echo "Valid"
+fi
+```
+
+### Loop Variables
+
+Use descriptive names, even for simple loops:
+
+```bash
+# ✅ Good
+for file in *.txt; do
+  echo "$file"
+done
+
+for user in "${users[@]}"; do
+  echo "$user"
+done
+
+# ❌ Avoid single letters (except for very short loops)
+for i in {1..10}; do  # OK for numeric iteration
+  echo "$i"
+done
+
+for f in *.txt; do  # Avoid - use 'file' instead
+  echo "$f"
+done
+```
+
+### Temporary Variables
+
+Prefix with `tmp_` or `temp_`:
+
+```bash
+tmp_file="/tmp/data_$$.txt"
+temp_dir="$(mktemp -d)"
+tmp_result=""
+```
+
+## Functions
+
+### Function Names
+
+**Use lowercase with underscores** (snake_case):
+
+```bash
+# ✅ Correct
+function process_data() {
+  # ...
+}
+
+function validate_input() {
+  # ...
+}
+
+function get_user_info() {
+  # ...
+}
+
+# ❌ Incorrect
+function processData() {  # camelCase
+  # ...
+}
+
+function Process-Data() {  # PascalCase
+  # ...
+}
+```
+
+### Verb-Noun Pattern
+
+Use descriptive verb-noun combinations:
+
+```bash
+# ✅ Good verbs
+get_user_data()
+set_configuration()
+validate_email()
+parse_json()
+format_output()
+check_permissions()
+create_backup()
+delete_temp_files()
+update_database()
+send_notification()
+
+# ❌ Vague names
+do_stuff()
+handle()
+process()
+run()
+```
+
+### Private/Internal Functions
+
+Prefix with underscore `_`:
+
+```bash
+# Public function
+function deploy_application() {
+  _validate_environment
+  _build_artifacts
+  _upload_to_server
+}
+
+# Private helper functions
+function _validate_environment() {
+  # ...
+}
+
+function _build_artifacts() {
+  # ...
+}
+
+function _upload_to_server() {
+  # ...
+}
+```
+
+## Arrays
+
+### Array Names
+
+Use plural nouns:
+
+```bash
+# ✅ Correct
+files=()
+users=("alice" "bob" "charlie")
+error_messages=()
+config_options=()
+
+# ❌ Incorrect
+file=()  # Singular
+user_list=("alice" "bob")  # Redundant 'list'
+```
+
+### Associative Arrays
+
+Use descriptive names with `_map` or `_dict` suffix (optional):
+
+```bash
+declare -A user_map
+user_map["alice"]="admin"
+user_map["bob"]="user"
+
+declare -A config
+config["host"]="localhost"
+config["port"]="5432"
+```
+
+## File and Directory Names
+
+### Script Files
+
+```bash
+# ✅ Good
+backup_database.sh
+deploy_application.sh
+process_logs.sh
+validate_config.sh
+
+# ❌ Avoid
+BackupDatabase.sh  # PascalCase
+backup-database.sh  # kebab-case (harder to source)
+bkup_db.sh  # Abbreviations
+```
+
+### Configuration Files
+
+```bash
+# ✅ Good
+.bashrc
+.bash_profile
+config.sh
+settings.conf
+
+# ❌ Avoid
+Config.sh
+SETTINGS.CONF
+```
+
+## Special Variables
+
+### Positional Parameters
+
+Document clearly:
+
+```bash
+function process_file() {
+  local input_file="$1"
+  local output_file="$2"
+  local options="${3:-}"  # Optional parameter with default
+  
+  # Use descriptive names, not $1, $2, $3
+}
+```
+
+### Special Shell Variables
+
+Know and use appropriately:
+
+```bash
+# Process ID
+echo "$$"
+
+# Last background process ID
+echo "$!"
+
+# Exit status of last command
+echo "$?"
+
+# Number of arguments
+echo "$#"
+
+# All arguments as separate words
+echo "$@"
+
+# All arguments as single word
+echo "$*"
+
+# Script name
+echo "$0"
+```
+
+## Naming Anti-Patterns
+
+### Avoid
+
+```bash
+# ❌ Single letter variables (except loop counters)
+a="value"
+x=10
+
+# ❌ Abbreviations
+usr_nm="john"
+cfg_pth="/etc/config"
+tmp_fl="/tmp/file"
+
+# ❌ Hungarian notation
+str_name="john"
+int_count=5
+bool_is_valid=true
+
+# ❌ Redundant prefixes
+var_user_name="john"
+func_process_data() { }
+
+# ❌ Inconsistent naming
+userName="john"
+file_path="/tmp"
+MAX-RETRIES=3
+```
+
+### Use Instead
+
+```bash
+# ✅ Descriptive names
+user_name="john"
+config_path="/etc/config"
+temp_file="/tmp/file"
+
+# ✅ Clear types from context
+name="john"
+count=5
+is_valid=true
+
+# ✅ Consistent style
+user_name="john"
+file_path="/tmp"
+MAX_RETRIES=3
+```
+
+## Best Practices Summary
+
+1. **Variables**: lowercase_with_underscores
+2. **Constants**: UPPERCASE_WITH_UNDERSCORES
+3. **Functions**: lowercase_with_underscores (verb_noun pattern)
+4. **Arrays**: plural_nouns
+5. **Booleans**: is_/has_/should_/can_ prefix
+6. **Private functions**: _leading_underscore
+7. **Temporary variables**: tmp_/temp_ prefix
+8. **Be descriptive**: Avoid abbreviations
+9. **Be consistent**: Same style throughout
+10. **Document parameters**: Use local variables with clear names
+