aidevops 2.52.1

package/.agent/tools/code-review/code-standards.md

@@ -0,0 +1,309 @@
+---
+description: Documented code quality standards for compliance checking
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Code Standards - Quality Rules Reference
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Reference documentation for code quality standards
+- **Platforms**: SonarCloud, CodeFactor, Codacy, ShellCheck
+- **Target**: A-grade across all platforms, zero critical violations
+
+**Critical Rules (Zero Tolerance)**:
+
+| Rule | Description | Pattern |
+|------|-------------|---------|
+| S7682 | Explicit return statements | `return 0` or `return 1` in every function |
+| S7679 | No direct positional params | `local param="$1"` not `$1` directly |
+| S1192 | Constants for repeated strings | `readonly MSG="text"` for 3+ uses |
+| S1481 | No unused variables | Remove or use declared variables |
+| ShellCheck | Zero violations | All scripts pass `shellcheck` |
+
+**Validation Commands**:
+
+```bash
+# Run local linting
+~/.aidevops/agents/scripts/linters-local.sh
+
+# Check specific rules
+grep -L "return [01]" .agent/scripts/*.sh  # S7682
+grep -n '\$[1-9]' .agent/scripts/*.sh | grep -v 'local.*=.*\$[1-9]'  # S7679
+```
+
+**Workflow Position**: Reference during development, validated by `/linters-local`
+
+<!-- AI-CONTEXT-END -->
+
+## Purpose
+
+This document defines the **authoritative code quality standards** for the aidevops framework. Use this as a reference during development to ensure compliance.
+
+**Related commands**:
+- `/linters-local` - Validates these standards locally
+- `/code-audit-remote` - Validates via external services
+- `/pr` - Orchestrates all checks
+
+## Critical Standards (Zero Tolerance)
+
+### S7682 - Return Statements
+
+Every function MUST have an explicit `return 0` or `return 1`.
+
+```bash
+# CORRECT - Always explicit return
+function_name() {
+    local param="$1"
+    # Function logic
+    return 0  # MANDATORY
+}
+
+# INCORRECT - Missing return statement
+function_name() {
+    local param="$1"
+    # Function logic
+}  # This causes S7682 violation
+```
+
+**Validation**:
+
+```bash
+grep -L "return [01]" .agent/scripts/*.sh
+```
+
+### S7679 - Positional Parameters
+
+NEVER use positional parameters directly. Always assign to local variables first.
+
+```bash
+# CORRECT - Local variable assignment
+main() {
+    local command="${1:-help}"
+    local account_name="$2"
+    local target="$3"
+
+    case "$command" in
+        "list")
+            list_items "$account_name"  # Use local variable
+            ;;
+    esac
+    return 0
+}
+
+# INCORRECT - Direct positional parameter usage
+main() {
+    case "$1" in  # This causes S7679 violation
+        "list")
+            list_items "$2"  # This causes S7679 violation
+            ;;
+    esac
+}
+```
+
+**Validation**:
+
+```bash
+grep -n '\$[1-9]' .agent/scripts/*.sh | grep -v 'local.*=.*\$[1-9]'
+```
+
+### S1192 - String Literals
+
+Define constants for strings used 3 or more times.
+
+```bash
+# CORRECT - Constants at file top
+readonly ERROR_ACCOUNT_REQUIRED="Account name is required"
+readonly ERROR_CONFIG_NOT_FOUND="Configuration file not found"
+readonly SUCCESS_OPERATION_COMPLETE="Operation completed successfully"
+
+# Use constants instead of literals
+print_error "$ERROR_ACCOUNT_REQUIRED"
+print_error "$ERROR_CONFIG_NOT_FOUND"
+
+# INCORRECT - Repeated string literals
+print_error "Account name is required"  # Repeated 3+ times
+print_error "Account name is required"  # Causes S1192 violation
+```
+
+**Validation**:
+
+```bash
+for file in .agent/scripts/*.sh; do
+    echo "=== $file ==="
+    grep -o '"[^"]*"' "$file" | sort | uniq -c | sort -nr | head -5
+done
+```
+
+### S1481 - Unused Variables
+
+Only declare variables that are actually used.
+
+```bash
+# CORRECT - Only used variables
+function_name() {
+    local used_param="$1"
+    echo "$used_param"
+    return 0
+}
+
+# INCORRECT - Unused variable declaration
+function_name() {
+    local used_param="$1"
+    local unused_param="$2"  # This causes S1481 violation
+    echo "$used_param"
+    return 0
+}
+```
+
+### ShellCheck Compliance
+
+All shell scripts must pass ShellCheck with zero violations.
+
+```bash
+# Validate all scripts
+find .agent/scripts/ -name "*.sh" -exec shellcheck {} \;
+
+# Validate single script
+shellcheck script.sh
+```
+
+## Security Hotspots (Acceptable Patterns)
+
+SonarCloud flags these patterns as security hotspots. They are acceptable when properly documented:
+
+### HTTP String Detection (S5332)
+
+When checking for insecure URLs, not using them:
+
+```bash
+# CORRECT - Detection with comment
+# SONAR: Detecting insecure URLs for security audit, not using them
+non_https=$(echo "$data" | jq '[.items[] | select(.url | startswith("http://"))] | length')
+
+# INCORRECT - No documentation
+non_https=$(echo "$data" | jq '[.items[] | select(.url | startswith("http://"))] | length')
+```
+
+### Localhost HTTP Output (S5332)
+
+Local development environments often lack SSL:
+
+```bash
+# CORRECT - Intentional localhost HTTP
+if [[ "$ssl" == "true" ]]; then
+    print_info "Access your app at: https://$domain"
+else
+    # SONAR: Local dev without SSL is intentional
+    print_info "Access your app at: http://$domain"
+fi
+```
+
+### Curl Pipe to Bash (S4423)
+
+For official installers from verified sources:
+
+```bash
+# CORRECT - Documented official installer
+# SONAR: Official Bun installer from verified HTTPS source
+curl -fsSL https://bun.sh/install | bash
+
+# BETTER - Download and inspect first (for new/unknown sources)
+curl -fsSL https://example.com/install.sh -o /tmp/install.sh
+less /tmp/install.sh  # Review script
+bash /tmp/install.sh
+```
+
+**When to suppress vs fix:**
+
+- **Suppress**: Official installers (bun, nvm, rustup), localhost dev, URL detection
+- **Fix**: Actual HTTP usage in production, unverified installer sources
+
+## Platform Targets
+
+### SonarCloud
+
+| Metric | Target |
+|--------|--------|
+| Quality Gate | Passed |
+| Bugs | 0 |
+| Vulnerabilities | 0 |
+| Code Smells | <50 |
+| Technical Debt | <400 minutes |
+| Security Rating | A |
+| Reliability Rating | A |
+| Maintainability Rating | A |
+
+### CodeFactor
+
+| Metric | Target |
+|--------|--------|
+| Overall Grade | A |
+| A-grade Files | >85% |
+| Critical Issues | 0 |
+
+### Codacy
+
+| Metric | Target |
+|--------|--------|
+| Grade | A |
+| Security Issues | 0 |
+| Error Prone | 0 |
+
+## Pre-Commit Checklist
+
+Before committing, verify:
+
+```bash
+# 1. Run local linting
+~/.aidevops/agents/scripts/linters-local.sh
+
+# 2. Check return statements
+grep -L "return [01]" .agent/scripts/*.sh
+
+# 3. Check positional parameters
+grep -n '\$[1-9]' .agent/scripts/*.sh | grep -v 'local.*=.*\$[1-9]'
+
+# 4. Run ShellCheck
+find .agent/scripts/ -name "*.sh" -exec shellcheck {} \;
+
+# 5. Check for secrets
+~/.aidevops/agents/scripts/secretlint-helper.sh scan
+```
+
+## Quality Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `linters-local.sh` | Run all local quality checks |
+| `quality-fix.sh` | Auto-fix common issues |
+| `pre-commit-hook.sh` | Git pre-commit validation |
+| `secretlint-helper.sh` | Secret detection |
+
+## Current Status
+
+**Multi-Platform Excellence Achieved:**
+
+- **SonarCloud**: A-grade maintained
+- **CodeFactor**: A-grade overall
+- **Codacy**: Enterprise-grade compliance
+- **Critical Issues**: S7679 & S1481 = 0 (RESOLVED)
+
+## Related Documentation
+
+- **Local linting**: `scripts/linters-local.sh`
+- **Remote auditing**: `workflows/code-audit-remote.md`
+- **Unified PR review**: `workflows/pr.md`
+- **Automation guide**: `tools/code-review/automation.md`
+- **Best practices**: `tools/code-review/best-practices.md`

package/.agent/tools/code-review/coderabbit.md

@@ -0,0 +1,101 @@
+---
+description: CodeRabbit AI code review integration
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# CodeRabbit Analysis Trigger
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- Purpose: Trigger CodeRabbit AI analysis on pull requests
+- Analysis scope: Shell scripts (.agent/scripts/), MCP configs, docs/
+- Goals: Code quality improvements, framework enhancements, documentation quality
+- Expected fixes: Variable quoting, error handling, return checks, path handling
+- Config validation: JSON schema, env vars, API keys, security
+- Docs fixes: Markdown linting, code blocks, links, formatting
+- Post-analysis: Review suggestions, apply auto-fixes, test, commit, close PR
+<!-- AI-CONTEXT-END -->
+
+This file is created to trigger CodeRabbit analysis and gather auto-fix recommendations.
+
+## 🎯 **Analysis Goals**
+
+### **Code Quality Improvements**
+
+- Identify potential auto-fixes for shell scripts
+- Analyze MCP integration code for best practices
+- Review documentation for consistency and clarity
+- Detect any security or performance issues
+
+### **Framework Enhancements**
+
+- Validate MCP configuration templates
+- Review setup and validation scripts
+- Analyze error handling patterns
+- Check for code duplication or optimization opportunities
+
+### **Documentation Quality**
+
+- Review Markdown formatting and structure
+- Validate code examples and snippets
+- Check for broken links or references
+- Ensure consistency across documentation files
+
+## 🔧 **Expected Auto-Fixes**
+
+### **Shell Script Improvements**
+
+- Variable quoting and expansion
+- Error handling enhancements
+- Function return value checks
+- Path handling improvements
+
+### **Configuration Validation**
+
+- JSON schema validation
+- Environment variable handling
+- API key management best practices
+- Security configuration reviews
+
+### **Documentation Enhancements**
+
+- Markdown linting fixes
+- Code block language specifications
+- Link validation and updates
+- Formatting consistency improvements
+
+## 📊 **Analysis Scope**
+
+This analysis covers:
+
+- All shell scripts in `.agent/scripts/`
+- MCP configuration templates in `configs/mcp-templates/`
+- Documentation files in `docs/`
+- Main README.md and configuration files
+- Setup and validation automation scripts
+
+## 🚀 **Post-Analysis Actions**
+
+After CodeRabbit analysis:
+
+1. Review all suggested improvements
+2. Apply auto-fixes where appropriate
+3. Implement manual fixes for complex issues
+4. Update documentation based on recommendations
+5. Re-run validation scripts to ensure functionality
+6. Commit improvements and close this PR
+
+---
+
+**This PR will be closed after CodeRabbit analysis is complete and recommendations are implemented.**

package/.agent/tools/code-review/management.md

@@ -0,0 +1,155 @@
+---
+description: Quality management and monitoring specification
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# Quality Management Specification
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- Methodology: Zero technical debt through systematic resolution
+- Core principle: Enhance functionality, never delete to fix issues
+- Priority order: S7679 (critical) -> S1481 -> S1192 -> S7682 -> ShellCheck
+- S7679 fix: Use `printf '%s50/month\n' '$'` instead of `echo "$50/month"`
+- S1481 fix: Enhance usage of variable or remove if truly unused
+- S1192 fix: Create `readonly CONSTANT="repeated string"` at file top
+- Key scripts: linters-local.sh, quality-fix.sh, quality-cli-manager.sh
+- Achievement: 349 -> 42 issues (88% reduction), 100% critical resolved
+- Success: Zero S7679/S1481, <10 S1192, 100% feature retention
+<!-- AI-CONTEXT-END -->
+
+## Zero Technical Debt Methodology
+
+> **Note**: This document is supplementary to the [AGENTS.md](../AGENTS.md).
+> For any conflicts, the main AGENTS.md takes precedence as the single source of truth.
+
+### Overview
+
+This document provides detailed methodology and historical context for our systematic approach to achieving zero technical debt. Current status: SonarCloud issues reduced from 349 to 66 (81% reduction) while enhancing functionality.
+
+### Core Principles
+
+#### 1. Functionality Enhancement Over Deletion
+
+- **Never remove functionality** to fix quality issues
+- **Enhance existing code** to resolve violations
+- **Add value** while addressing technical debt
+- **Preserve all user-facing features** throughout quality improvements
+
+#### 2. Systematic Priority-Based Resolution
+
+**Priority Order (SonarCloud Rule Severity):**
+
+1. **S7679 (Positional Parameters)** - Critical shell interpretation issues
+2. **S1481 (Unused Variables)** - Code clarity and maintenance
+3. **S1192 (String Literals)** - Code duplication and maintainability
+4. **S7682 (Return Statements)** - Function consistency
+5. **ShellCheck Issues** - Best practices and style
+
+#### 3. Automation-First Approach
+
+- **Create reusable tools** for each issue type
+- **Batch process** similar violations across files
+- **Document patterns** for future maintenance
+- **Build quality gates** into development workflow
+
+### Issue Resolution Patterns
+
+#### Positional Parameters (S7679) - RESOLVED ✅
+
+**Problem**: Shell interpreting `$50`, `$200` as positional parameters
+**Solution**: Use printf format strings
+
+```bash
+# ❌ BEFORE (triggers S7679)
+echo "Price: $50/month"
+
+# ✅ AFTER (compliant)
+printf 'Price: %s50/month\n' '$'
+```
+
+#### Unused Variables (S1481) - RESOLVED ✅
+
+**Problem**: Variables assigned but never used
+**Solutions**:
+
+1. **Enhance functionality** (preferred)
+2. **Remove if truly unused**
+3. **Use in logging/debugging**
+
+```bash
+# ❌ BEFORE (unused variable)
+local port
+read -r port
+
+# ✅ AFTER (enhanced functionality)
+local port
+read -r port
+if [[ -n "$port" && "$port" != "22" ]]; then
+    ssh -p "$port" "$host"
+else
+    ssh "$host"
+fi
+```
+
+#### String Literals (S1192) - MAJOR PROGRESS 📊
+
+**Problem**: Repeated string literals (3+ occurrences)
+**Solution**: Create readonly constants
+
+```bash
+# ❌ BEFORE (repeated literals)
+curl -H "Content-Type: application/json"
+curl -H "Content-Type: application/json"
+curl -H "Content-Type: application/json"
+
+# ✅ AFTER (constant usage)
+readonly CONTENT_TYPE_JSON="Content-Type: application/json"
+curl -H "$CONTENT_TYPE_JSON"
+curl -H "$CONTENT_TYPE_JSON"
+curl -H "$CONTENT_TYPE_JSON"
+```
+
+### Quality Tools & Scripts
+
+#### Automated Quality Tools
+
+- **linters-local.sh**: Comprehensive multi-platform quality validation
+- **fix-content-type.sh**: Content-Type header consolidation
+- **fix-auth-headers.sh**: Authorization header standardization
+- **fix-error-messages.sh**: Common error message constants
+- **markdown-formatter.sh**: Markdown quality compliance
+
+#### Quality CLI Integration
+
+- **CodeRabbit CLI**: AI-powered code review
+- **Codacy CLI v2**: Comprehensive static analysis
+- **SonarScanner CLI**: SonarCloud integration
+- **quality-cli-manager.sh**: Unified CLI management
+
+### Measurement & Tracking
+
+#### Key Metrics
+
+- **SonarCloud Issues**: 349 → 42 (88% reduction)
+- **Critical Violations**: S7679 & S1481 = 0 (100% resolved)
+- **String Literals**: 50+ violations eliminated
+- **Code Quality**: A-grade maintained across platforms
+
+#### Success Criteria
+
+- **Zero Critical Issues**: S7679, S1481 completely resolved
+- **Minimal String Duplication**: <10 S1192 violations
+- **ShellCheck Compliance**: <5 critical violations per file
+- **Functionality Preservation**: 100% feature retention