aidevops 2.52.1

package/.agent/tools/git/github-actions.md

@@ -0,0 +1,207 @@
+---
+description: GitHub Actions CI/CD workflow setup and management
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# GitHub Actions Setup Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Workflow File**: `.github/workflows/code-quality.yml`
+- **Triggers**: Push to main/develop, PRs to main
+- **Jobs**: Framework validation, SonarCloud analysis, Codacy analysis
+- **Required Secrets**: `SONAR_TOKEN` (configured), `CODACY_API_TOKEN` (needs setup)
+- **Auto-Provided**: `GITHUB_TOKEN` by GitHub
+- **SonarCloud Dashboard**: https://sonarcloud.io/project/overview?id=marcusquinn_aidevops
+- **Codacy Dashboard**: https://app.codacy.com/gh/marcusquinn/aidevops
+- **Actions URL**: https://github.com/marcusquinn/aidevops/actions
+- **Add Secrets**: Repository Settings → Secrets and variables → Actions
+<!-- AI-CONTEXT-END -->
+
+## Automated Code Quality Analysis
+
+### Current GitHub Actions Status
+
+#### ✅ Configured and Working:
+
+- **SonarCloud Analysis**: ✅ Runs on every push and PR
+- **Framework Validation**: ✅ Validates repository structure
+- **Security Scanning**: ✅ Checks for hardcoded API keys
+
+#### Requires Setup:
+
+- **Codacy Analysis**: Requires `CODACY_API_TOKEN` secret
+
+## Required GitHub Repository Secrets
+
+### **1. SONAR_TOKEN (Already Configured)**
+
+- **Status**: ✅ **CONFIGURED**
+- **Purpose**: SonarCloud analysis in GitHub Actions
+- **Value**: Your SonarCloud API token
+- **Source**: https://sonarcloud.io/account/security
+
+### **2. CODACY_API_TOKEN (Needs Setup)**
+
+- **Status**: ❌ **NEEDS CONFIGURATION**
+- **Purpose**: Codacy analysis in GitHub Actions
+- **Value**: Your Codacy API token
+- **Source**: https://app.codacy.com/account/api-tokens
+
+## Setup Instructions
+
+### **Add Missing GitHub Secret:**
+
+1. **Go to Repository Settings**:
+
+   ```text
+   https://github.com/marcusquinn/aidevops/settings/secrets/actions
+   ```
+
+2. **Click "New repository secret"**
+
+3. **Add Codacy Secret**:
+   - **Name**: `CODACY_API_TOKEN`
+   - **Value**: Your Codacy API token (get from secure local storage)
+
+## Workflow Triggers
+
+### **Automatic Execution:**
+
+- **Push to main**: ✅ Triggers full analysis
+- **Push to develop**: ✅ Triggers full analysis
+- **Pull Request to main**: ✅ Triggers full analysis
+
+### **Analysis Jobs:**
+
+1. **Framework Validation**: Repository structure and security checks
+2. **SonarCloud Analysis**: Code quality, security, and maintainability
+3. **Codacy Analysis**: Code quality and complexity analysis
+
+## Viewing Results
+
+### **SonarCloud Dashboard:**
+
+```text
+https://sonarcloud.io/project/overview?id=marcusquinn_aidevops
+```
+
+### **Codacy Dashboard:**
+
+```text
+https://app.codacy.com/gh/marcusquinn/aidevops
+```
+
+### **GitHub Actions:**
+
+```text
+https://github.com/marcusquinn/aidevops/actions
+```
+
+## Workflow Configuration
+
+### **File**: `.github/workflows/code-quality.yml`
+
+#### **Key Features:**
+
+- **Multi-job workflow** with framework validation and code analysis
+- **Security scanning** to prevent API key exposure
+- **Conditional Codacy analysis** (runs only if token is configured)
+- **Comprehensive reporting** with links to analysis dashboards
+- **Fail-fast security** checks to prevent credential exposure
+
+#### **Environment Variables Used:**
+
+- `GITHUB_TOKEN`: Automatic (provided by GitHub)
+- `SONAR_TOKEN`: From repository secrets
+- `CODACY_API_TOKEN`: From repository secrets (optional)
+
+## Security Features
+
+### **Automated Security Checks:**
+
+- **API Key Detection**: Scans for hardcoded credentials
+- **Repository Structure**: Validates framework integrity
+- **Secret Management**: Uses GitHub Secrets for sensitive data
+
+### **Security Best Practices:**
+
+- **No secrets in code**: All API keys use GitHub Secrets
+- **Conditional execution**: Graceful handling of missing secrets
+- **Fail-fast security**: Stops workflow if security issues detected
+
+## Workflow Patterns
+
+### Handling Concurrent Push Failures
+
+When GitHub Actions workflows push to repositories, concurrent runs can cause push failures due to race conditions. Use these patterns for workflows that commit and push:
+
+#### Full Retry Pattern (Recommended for External Repos)
+
+```yaml
+# Retry loop to handle concurrent pushes (up to 3 attempts)
+for i in 1 2 3; do
+  echo "Push attempt $i..."
+  git pull --rebase origin main || true
+  if git push; then
+    echo "Push succeeded on attempt $i"
+    exit 0
+  fi
+  echo "Push failed, waiting before retry..."
+  sleep $((i * 5))  # Exponential backoff: 5s, 10s, 15s
+done
+
+echo "All push attempts failed"
+exit 1
+```
+
+#### Simple Pattern (For Same-Repo Auto-Fixes)
+
+```yaml
+# Pull with rebase to handle concurrent pushes, then push
+git pull --rebase origin main || true
+git push
+```
+
+#### When to Use Each Pattern
+
+| Scenario | Pattern | Rationale |
+|----------|---------|-----------|
+| Pushing to external repo | Full retry | Higher chance of conflicts |
+| Auto-fix commits to same repo | Simple | Usually succeeds |
+| Wiki sync | Full retry | Wiki can have manual edits |
+| Release workflows | Simple | Should be serialized anyway |
+
+#### Key Points
+
+- Always `git pull --rebase` before pushing to incorporate remote changes
+- Use `|| true` after pull to continue even if pull fails (empty repo, etc.)
+- Exponential backoff (`sleep $((i * 5))`) reduces collision probability
+- Exit with error after all retries fail to surface the issue
+
+## Next Steps
+
+1. **Add CODACY_API_TOKEN** to GitHub repository secrets
+2. **Push a commit** to trigger the workflow
+3. **Verify analysis results** in SonarCloud and Codacy dashboards
+4. **Monitor workflow runs** in GitHub Actions
+
+## Benefits
+
+- **Automated Quality Gates**: Every commit analyzed for quality
+- **Security Monitoring**: Prevents credential exposure
+- **Multi-Platform Analysis**: SonarCloud + Codacy coverage
+- **Professional Standards**: Industry-grade CI/CD pipeline
+
+**Your repository now has comprehensive automated code quality analysis running on every commit!**

package/.agent/tools/git/github-cli.md

@@ -0,0 +1,223 @@
+---
+description: GitHub CLI (gh) for repos, PRs, issues, and actions
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# GitHub CLI Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **CLI Tool**: `gh` (GitHub CLI) - the official GitHub CLI
+- **Install**: `brew install gh` (macOS) | `apt install gh` (Ubuntu)
+- **Auth**: `gh auth login` (stores token in keyring)
+- **Status**: `gh auth status`
+- **Docs**: https://cli.github.com/manual
+
+**Common Commands**:
+
+```bash
+gh repo list                    # List your repos
+gh repo create NAME             # Create repo
+gh issue list                   # List issues
+gh issue create                 # Create issue
+gh pr list                      # List PRs
+gh pr create                    # Create PR
+gh pr merge                     # Merge PR
+gh release create TAG           # Create release
+gh release list                 # List releases
+```
+
+**Multi-Account**: `gh auth login` supports multiple accounts via keyring
+<!-- AI-CONTEXT-END -->
+
+## Overview
+
+The `gh` CLI is the official GitHub command-line tool. It handles authentication securely via your system keyring and provides comprehensive access to GitHub features. **Use `gh` directly rather than wrapper scripts.**
+
+## Installation
+
+```bash
+# macOS
+brew install gh
+
+# Ubuntu/Debian
+sudo apt install gh
+
+# Other platforms
+# See: https://cli.github.com/manual/installation
+```
+
+## Authentication
+
+```bash
+# Login (interactive - stores token in keyring)
+gh auth login
+
+# Check auth status
+gh auth status
+
+# Get current token (for scripts that need GITHUB_TOKEN)
+gh auth token
+```
+
+Authentication is stored securely in your system keyring. No need for `GITHUB_TOKEN` environment variable for normal `gh` operations.
+
+## Repository Management
+
+```bash
+# List your repositories
+gh repo list
+
+# Create new repository
+gh repo create my-repo --public --description "My project"
+
+# Clone a repository
+gh repo clone owner/repo
+
+# View repository info
+gh repo view owner/repo
+
+# Fork a repository
+gh repo fork owner/repo
+```
+
+## Issue Management
+
+```bash
+# List issues
+gh issue list
+gh issue list --state open --label bug
+
+# Create issue
+gh issue create --title "Bug report" --body "Description"
+
+# View issue
+gh issue view 123
+
+# Close issue
+gh issue close 123
+```
+
+## Pull Request Management
+
+```bash
+# List PRs
+gh pr list
+gh pr list --state open
+
+# Create PR
+gh pr create --title "Feature X" --body "Description"
+gh pr create --fill  # Auto-fill from commits
+
+# View PR
+gh pr view 123
+
+# Merge PR
+gh pr merge 123 --squash
+gh pr merge 123 --merge
+gh pr merge 123 --rebase
+```
+
+## Release Management
+
+```bash
+# Create release with auto-generated notes
+gh release create v1.2.3 --generate-notes
+
+# Create release with custom notes
+gh release create v1.2.3 --notes "Release notes here"
+
+# Create draft release
+gh release create v1.2.3 --draft --generate-notes
+
+# List releases
+gh release list
+
+# View latest release
+gh release view
+
+# Download release assets
+gh release download v1.2.3
+```
+
+## Workflow/Actions
+
+```bash
+# List workflow runs
+gh run list
+
+# View run details
+gh run view 123456
+
+# Watch a running workflow
+gh run watch
+
+# Re-run failed jobs
+gh run rerun 123456 --failed
+```
+
+## API Access
+
+```bash
+# Make API calls directly
+gh api repos/owner/repo
+gh api repos/owner/repo/issues
+
+# Create via API
+gh api repos/owner/repo/issues -f title="Bug" -f body="Details"
+```
+
+## Multi-Account Support
+
+The `gh` CLI supports multiple accounts:
+
+```bash
+# Login to additional account
+gh auth login
+
+# Switch between accounts
+gh auth switch
+
+# List authenticated accounts
+gh auth status
+```
+
+## Environment Variables
+
+For scripts that need a token:
+
+```bash
+# Get token from gh auth
+export GITHUB_TOKEN=$(gh auth token)
+
+# Or use GH_TOKEN (preferred by gh)
+export GH_TOKEN=$(gh auth token)
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "not logged in" | Run `gh auth login` |
+| "token expired" | Run `gh auth refresh` |
+| Wrong account | Run `gh auth switch` |
+| Need token for script | Use `$(gh auth token)` |
+
+## Best Practices
+
+1. **Use `gh` directly** - No wrapper scripts needed
+2. **Use keyring auth** - More secure than env vars
+3. **Use `--generate-notes`** - Auto-generate release notes from commits/PRs
+4. **Use `gh api`** - For advanced GitHub API access
+5. **Use `gh pr create --fill`** - Auto-fill PR details from commits

package/.agent/tools/git/gitlab-cli.md

@@ -0,0 +1,190 @@
+---
+description: GitLab CLI (glab) for repos, MRs, issues, and pipelines
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# GitLab CLI Helper Documentation
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **CLI Tool**: `glab` (GitLab CLI)
+- **Install**: `brew install glab` (macOS) | `apt install glab` (Ubuntu)
+- **Auth**: `glab auth login` (GitLab.com) | `glab auth login --hostname gitlab.company.com` (self-hosted)
+- **Config**: `configs/gitlab-cli-config.json`
+- **Script**: `.agent/scripts/gitlab-cli-helper.sh`
+- **Requires**: `jq` for JSON parsing
+
+**Commands**: `list-projects|create-project|delete-project|list-issues|create-issue|close-issue|list-mrs|create-mr|merge-mr|list-branches|create-branch`
+
+**Usage**: `./providers/gitlab-cli-helper.sh [command] [account] [args]`
+
+**Multi-Instance**: Supports GitLab.com + self-hosted via instance_url in config
+<!-- AI-CONTEXT-END -->
+
+## Overview
+
+The GitLab CLI Helper provides a comprehensive interface for managing GitLab projects, issues, merge requests, and branches directly from the command line. It leverages the `glab` CLI tool to offer a seamless experience for developers working with GitLab.com and self-hosted instances.
+
+## Prerequisites
+
+1. **GitLab CLI (`glab`)**: Must be installed.
+    - **macOS**: `brew install glab`
+    - **Ubuntu/Debian**: `sudo apt install glab`
+    - **Other**: See [GitLab CLI Installation](https://glab.readthedocs.io/en/latest/installation/)
+2. **`jq`**: JSON processor (required for configuration parsing).
+3. **Authentication**: You must authenticate `glab` with your GitLab instance(s).
+
+## Configuration
+
+The helper uses a JSON configuration file located at `configs/gitlab-cli-config.json`.
+
+### Setup
+
+1. Copy the template:
+
+    ```bash
+    cp configs/gitlab-cli-config.json.txt configs/gitlab-cli-config.json
+    ```
+
+2. Edit `configs/gitlab-cli-config.json` with your account details.
+
+### Multi-Account/Instance Support
+
+The configuration supports multiple accounts and instances (e.g., `primary` for GitLab.com, `work` for self-hosted).
+
+**1. Authenticate `glab`:**
+
+```bash
+# For GitLab.com
+glab auth login
+
+# For Self-Hosted
+glab auth login --hostname gitlab.company.com
+```
+
+**2. Update `configs/gitlab-cli-config.json`:**
+
+```json
+{
+  "accounts": {
+    "primary": {
+      "instance_url": "https://gitlab.com",
+      "owner": "your-username",
+      "default_visibility": "public"
+    },
+    "work": {
+      "instance_url": "https://gitlab.company.com",
+      "owner": "work-username",
+      "default_visibility": "private"
+    }
+  }
+}
+```
+
+## Usage
+
+Run the helper script:
+
+```bash
+./providers/gitlab-cli-helper.sh [command] [account] [arguments]
+```
+
+### Project Management
+
+- **List Projects**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh list-projects primary
+    ```
+
+- **Create Project**:
+
+    ```bash
+    # Usage: create-project <account> <name> [desc] [visibility] [init]
+    ./providers/gitlab-cli-helper.sh create-project primary my-new-project "Description" private true
+    ```
+
+- **Get Project Details**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh get-project primary my-new-project
+    ```
+
+- **Delete Project**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh delete-project primary my-new-project
+    ```
+
+### Issue Management
+
+- **List Issues**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh list-issues primary my-project opened
+    ```
+
+- **Create Issue**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh create-issue primary my-project "Bug Title" "Issue description"
+    ```
+
+- **Close Issue**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh close-issue primary my-project 1
+    ```
+
+### Merge Request Management
+
+- **List Merge Requests**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh list-mrs primary my-project opened
+    ```
+
+- **Create Merge Request**:
+
+    ```bash
+    # Usage: create-mr <account> <project> <title> <source> [target] [desc]
+    ./providers/gitlab-cli-helper.sh create-mr primary my-project "Feature X" feature-branch main "Description"
+    ```
+
+- **Merge Merge Request**:
+
+    ```bash
+    # Usage: merge-mr <account> <project> <mr_number> [method]
+    ./providers/gitlab-cli-helper.sh merge-mr primary my-project 1 squash
+    ```
+
+### Branch Management
+
+- **List Branches**:
+
+    ```bash
+    ./providers/gitlab-cli-helper.sh list-branches primary my-project
+    ```
+
+- **Create Branch**:
+
+    ```bash
+    # Usage: create-branch <account> <project> <new_branch> [source_branch]
+    ./providers/gitlab-cli-helper.sh create-branch primary my-project feature-branch main
+    ```
+
+## Troubleshooting
+
+- **"GitLab CLI is not authenticated"**: Run `glab auth status` to check your login status for the configured hostname.
+- **"Instance URL not configured"**: Check `configs/gitlab-cli-config.json` and ensure the `instance_url` is correct for the account you are using.