xuanzhu 0.1.0

package/dist/skills/gmail/install.sh

@@ -0,0 +1,313 @@
+#!/bin/bash
+# Gmail CLI Installation Script - SECURE VERSION
+# This script implements security best practices:
+# - Virtual environment isolation
+# - Pinned dependencies with hash verification
+# - Secure file permissions
+# - Integrity checking
+
+set -euo pipefail  # Exit on error, undefined variables, pipe failures
+
+echo "🔒 Gmail CLI Secure Installation"
+echo "================================"
+echo ""
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+VENV_DIR="$PROJECT_ROOT/.venv-gmail-cli"
+BIN_DIR="$PROJECT_ROOT/.codebuddy/bin"
+GMAIL_CLI_PATH="$BIN_DIR/gmail-cli"
+REQUIREMENTS_LOCKED="$SCRIPT_DIR/requirements-locked.txt"
+REQUIREMENTS_FILE="$SCRIPT_DIR/requirements.txt"
+
+# Use locked requirements if available (has hashes for verification)
+if [ -f "$REQUIREMENTS_LOCKED" ]; then
+    REQUIREMENTS_FILE="$REQUIREMENTS_LOCKED"
+fi
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Logging functions
+log_info() { echo -e "${GREEN}✓${NC} $1"; }
+log_warn() { echo -e "${YELLOW}⚠️${NC} $1"; }
+log_error() { echo -e "${RED}❌${NC} $1"; }
+
+# Check if Python 3.7+ is installed
+echo "🔍 Checking prerequisites..."
+if ! command -v python3 &> /dev/null; then
+    log_error "Python 3 is not installed."
+    echo "Please install Python 3.7 or higher first."
+    exit 1
+fi
+
+PYTHON_VERSION=$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info[0])')
+PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info[1])')
+
+if [ "$PYTHON_MAJOR" -lt 3 ] || { [ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 7 ]; }; then
+    log_error "Python 3.7+ required. Found: $PYTHON_VERSION"
+    exit 1
+fi
+
+log_info "Python $PYTHON_VERSION found"
+
+# Check if pip is installed
+if ! python3 -m pip --version &> /dev/null; then
+    log_error "pip is not installed."
+    echo "Please install pip: python3 -m ensurepip --upgrade"
+    exit 1
+fi
+
+log_info "pip found: $(python3 -m pip --version)"
+echo ""
+
+# Create virtual environment for isolation
+echo "📦 Setting up isolated Python environment..."
+if [ -d "$VENV_DIR" ]; then
+    log_warn "Virtual environment already exists at: $VENV_DIR"
+    read -p "Remove and recreate? (y/N): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        rm -rf "$VENV_DIR"
+    else
+        echo "Using existing virtual environment"
+    fi
+fi
+
+if [ ! -d "$VENV_DIR" ]; then
+    python3 -m venv "$VENV_DIR"
+    log_info "Virtual environment created"
+fi
+
+# Activate virtual environment
+source "$VENV_DIR/bin/activate"
+log_info "Virtual environment activated"
+echo ""
+
+# Upgrade pip, setuptools, wheel
+echo "🔄 Upgrading pip and setuptools..."
+python -m pip install --upgrade pip setuptools wheel --quiet
+log_info "pip upgraded to: $(pip --version)"
+echo ""
+
+# Install dependencies with hash verification
+echo "🔐 Installing dependencies with integrity verification..."
+
+# Function to try hash-verified installation
+install_with_hashes() {
+    local req_file="$1"
+    # Check if requirements file has actual hash entries (not example placeholders)
+    if grep -q "^[^#].*--hash=sha256:[a-f0-9]\{64\}" "$req_file" 2>/dev/null; then
+        log_info "Found hash entries in requirements.txt, attempting verified installation"
+        if pip install --require-hashes -r "$req_file" 2>/dev/null; then
+            return 0
+        else
+            log_warn "Hash verification failed. Hashes may be outdated."
+            return 1
+        fi
+    fi
+    return 1
+}
+
+# Function to install without hashes (fallback)
+install_without_hashes() {
+    local req_file="$1"
+    log_warn "Installing without hash verification"
+    log_warn "For production, run: ./generate-hashes.sh to add integrity verification"
+    
+    # Strip comments and hashes, then install
+    pip install -r <(grep -v "^#" "$req_file" | grep -v "^\s*$" | sed 's/ *\\$//' | sed 's/--hash=sha256:[a-f0-9]*//')
+}
+
+if [ -f "$REQUIREMENTS_FILE" ]; then
+    log_info "Using requirements.txt from: $REQUIREMENTS_FILE"
+    
+    # Try hash-verified installation first, fall back to unverified
+    if ! install_with_hashes "$REQUIREMENTS_FILE"; then
+        install_without_hashes "$REQUIREMENTS_FILE"
+    fi
+    
+    if [ $? -eq 0 ]; then
+        log_info "Dependencies installed successfully"
+    else
+        log_error "Failed to install dependencies"
+        exit 1
+    fi
+else
+    log_warn "requirements.txt not found, installing packages directly"
+    pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib cryptography
+fi
+echo ""
+
+# Install security audit tool
+echo "🛡️ Installing security tools..."
+pip install pip-audit --quiet
+log_info "pip-audit installed (use 'pip-audit' to check for vulnerabilities)"
+echo ""
+
+# Run security audit
+echo "🔍 Running security audit on installed packages..."
+if pip-audit --desc 2>&1 | grep -q "No known vulnerabilities found"; then
+    log_info "No known vulnerabilities found in dependencies"
+else
+    log_warn "Security audit completed. Review output above for any vulnerabilities."
+fi
+echo ""
+
+# Setup secure credential directory
+echo "🔒 Setting up secure credential storage..."
+GMAIL_CLI_DIR="$HOME/.gmail-cli"
+
+if [ ! -d "$GMAIL_CLI_DIR" ]; then
+    mkdir -p "$GMAIL_CLI_DIR"
+    chmod 700 "$GMAIL_CLI_DIR"
+    log_info "Created secure directory: $GMAIL_CLI_DIR (permissions: 700)"
+else
+    # Check and fix permissions on existing directory
+    CURRENT_PERMS=$(stat -c %a "$GMAIL_CLI_DIR" 2>/dev/null || stat -f %A "$GMAIL_CLI_DIR" 2>/dev/null)
+    if [ "$CURRENT_PERMS" != "700" ]; then
+        log_warn "Fixing insecure permissions on $GMAIL_CLI_DIR"
+        chmod 700 "$GMAIL_CLI_DIR"
+        log_info "Permissions updated to 700 (owner-only access)"
+    else
+        log_info "Credential directory already secured: $GMAIL_CLI_DIR"
+    fi
+fi
+
+# Check and fix permissions on sensitive files if they exist
+for file in "credentials.json" "token.pickle"; do
+    FILEPATH="$GMAIL_CLI_DIR/$file"
+    if [ -f "$FILEPATH" ]; then
+        CURRENT_PERMS=$(stat -c %a "$FILEPATH" 2>/dev/null || stat -f %A "$FILEPATH" 2>/dev/null)
+        if [ "$CURRENT_PERMS" != "600" ]; then
+            log_warn "Fixing insecure permissions on $file"
+            chmod 600 "$FILEPATH"
+            log_info "Permissions updated to 600"
+        fi
+    fi
+done
+echo ""
+
+# Create bin directory if it doesn't exist
+echo "📂 Preparing binary directory..."
+mkdir -p "$BIN_DIR"
+log_info "Binary directory ready: $BIN_DIR"
+echo ""
+
+# Check if gmail-cli binary exists
+echo "🔍 Checking for gmail-cli binary..."
+if [ -f "$GMAIL_CLI_PATH" ]; then
+    log_info "gmail-cli binary found at: $GMAIL_CLI_PATH"
+    
+    # Check if it's executable
+    if [ ! -x "$GMAIL_CLI_PATH" ]; then
+        log_warn "Binary is not executable, fixing permissions..."
+        chmod 700 "$GMAIL_CLI_PATH"
+        log_info "Made binary executable (permissions: 700)"
+    fi
+else
+    log_warn "gmail-cli binary NOT found at: $GMAIL_CLI_PATH"
+    echo ""
+    echo "⚠️  SECURITY WARNING: Binary Missing"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "The gmail-cli Python script needs to be created."
+    echo ""
+    echo "IMPORTANT: Only use trusted sources for the binary!"
+    echo ""
+    echo "To create the binary:"
+    echo "  1. Review the example secure implementation in:"
+    echo "     $SCRIPT_DIR/gmail-cli-secure.py"
+    echo "  2. Customize for your needs"
+    echo "  3. Copy to: $GMAIL_CLI_PATH"
+    echo "  4. Make executable: chmod 700 $GMAIL_CLI_PATH"
+    echo ""
+    echo "DO NOT download binaries from untrusted sources!"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+fi
+echo ""
+
+# Create activation script
+ACTIVATE_SCRIPT="$SCRIPT_DIR/activate-gmail-cli.sh"
+cat > "$ACTIVATE_SCRIPT" << 'EOF'
+#!/bin/bash
+# Activate Gmail CLI virtual environment
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+VENV_DIR="$PROJECT_ROOT/.venv-gmail-cli"
+
+if [ -f "$VENV_DIR/bin/activate" ]; then
+    source "$VENV_DIR/bin/activate"
+    echo "✓ Gmail CLI virtual environment activated"
+    echo "Deactivate with: deactivate"
+else
+    echo "❌ Virtual environment not found. Run install.sh first."
+    exit 1
+fi
+EOF
+chmod +x "$ACTIVATE_SCRIPT"
+log_info "Created activation script: $ACTIVATE_SCRIPT"
+echo ""
+
+# Create wrapper script that uses the virtual environment
+WRAPPER_SCRIPT="$BIN_DIR/gmail-cli-wrapper"
+cat > "$WRAPPER_SCRIPT" << EOF
+#!/bin/bash
+# Gmail CLI Wrapper - Uses isolated virtual environment
+VENV_DIR="$VENV_DIR"
+GMAIL_CLI="$GMAIL_CLI_PATH"
+
+if [ ! -f "\$VENV_DIR/bin/activate" ]; then
+    echo "❌ Virtual environment not found. Run install.sh first."
+    exit 1
+fi
+
+source "\$VENV_DIR/bin/activate"
+exec python "\$GMAIL_CLI" "\$@"
+EOF
+chmod 700 "$WRAPPER_SCRIPT"
+log_info "Created wrapper script: $WRAPPER_SCRIPT"
+echo ""
+
+# Final summary
+echo "✅ Installation Complete!"
+echo "========================"
+echo ""
+echo "📋 Next Steps:"
+echo ""
+echo "1. 🔐 Set up OAuth2 credentials:"
+echo "   - Follow instructions in: $SCRIPT_DIR/SETUP.md"
+echo "   - Save credentials to: $GMAIL_CLI_DIR/credentials.json"
+echo "   - Ensure permissions: chmod 600 ~/.gmail-cli/credentials.json"
+echo ""
+echo "2. 🔨 Create the gmail-cli binary:"
+echo "   - Review example: $SCRIPT_DIR/gmail-cli-secure.py"
+echo "   - Copy to: $GMAIL_CLI_PATH"
+echo "   - Make executable: chmod 700 $GMAIL_CLI_PATH"
+echo ""
+echo "3. 🔑 Authenticate:"
+echo "   - Run: $WRAPPER_SCRIPT auth"
+echo ""
+echo "4. ✉️  Start using Gmail CLI:"
+echo "   - List emails: $WRAPPER_SCRIPT list --max 10"
+echo "   - Send email: $WRAPPER_SCRIPT send --to user@example.com --subject Test --body Hello"
+echo ""
+echo "📚 Documentation:"
+echo "   - Setup Guide: $SCRIPT_DIR/SETUP.md"
+echo "   - Security Guide: $SCRIPT_DIR/SECURITY.md"
+echo "   - Usage Examples: $SCRIPT_DIR/skill.md"
+echo ""
+echo "🛡️  Security Recommendations:"
+echo "   - Review SECURITY.md for best practices"
+echo "   - Run 'pip-audit' regularly to check for vulnerabilities"
+echo "   - Never commit credentials.json or token.pickle to git"
+echo "   - Enable full-disk encryption on your device"
+echo ""
+echo "Virtual environment: $VENV_DIR"
+echo "Activate manually: source $ACTIVATE_SCRIPT"
+echo ""

package/dist/skills/gmail/requirements.txt

@@ -0,0 +1,38 @@
+# Gmail CLI Python Dependencies
+# Pinned versions for security and reproducibility
+#
+# SECURITY NOTE:
+# For production deployments with hash verification:
+#   1. Run: ./generate-hashes.sh
+#   2. Use the generated requirements-locked.txt
+#   3. Install with: pip install --require-hashes -r requirements-locked.txt
+#
+# The install.sh script will automatically use hash verification
+# if requirements-locked.txt exists and contains valid hashes.
+
+# Google API Client - Core library for Gmail API
+# Provides the API client for accessing Gmail services
+google-api-python-client==2.108.0
+
+# Google Auth HTTPLib2 - HTTP transport for Google APIs
+# Required for making authenticated HTTP requests
+google-auth-httplib2==0.1.1
+
+# Google Auth OAuthLib - OAuth2 authentication
+# Handles OAuth2 flow for user authorization
+google-auth-oauthlib==1.1.0
+
+# Google Auth - Core authentication library
+# Base authentication functionality (explicit pin though installed as dependency)
+google-auth==2.23.4
+
+# Cryptography - Security operations
+# Used for secure credential storage and encryption
+# NOTE: Version 42.0.0+ contains security fixes for CVE-2023-49083 and others
+cryptography>=42.0.0
+
+# Security Best Practices:
+# - Run 'pip-audit' to check for known vulnerabilities
+# - Update dependencies regularly and regenerate hashes
+# - Use virtual environments for isolation
+# - For maximum security, use requirements-locked.txt with hash verification

package/dist/skills/gmail/skill.md

@@ -0,0 +1,225 @@
+---
+name: gmail
+description: Read, send, and manage Gmail emails via the gmail-cli tool.
+metadata:
+  displayName: Gmail
+  icon: mail
+  category: communication
+  version: 1.0.0
+  dependencies:
+    cli: gmail-cli
+    checkCommand: gmail-cli --version
+    bundledInstall: skills/gmail/install.sh
+    install:
+      darwin:
+        pip: gmail-cli
+      linux:
+        pip: gmail-cli
+      windows:
+        pip: gmail-cli
+  config:
+    - name: GMAIL_CREDENTIALS_PATH
+      label: Credentials Path
+      type: string
+      required: false
+      placeholder: ~/.gmail-cli/credentials.json
+  auth:
+    type: oauth
+    setupCommand: gmail-cli auth
+---
+
+# gmail-cli
+
+Use `./.codebuddy/bin/gmail-cli-wrapper` to interact with Gmail.
+This tool allows you to read, send, and manage Gmail messages directly from the chat.
+
+> **Note**: The wrapper script ensures commands run within an isolated Python virtual environment for security.
+
+## ⚠️ Security Warning
+
+**CRITICAL**: This tool accesses your Gmail account. Follow security best practices:
+
+- ✅ **ALWAYS** set file permissions: `chmod 700 ~/.gmail-cli && chmod 600 ~/.gmail-cli/*`
+- ✅ **NEVER** commit `credentials.json` or `token.pickle` to git
+- ✅ Use the secure installation script: `bash .codebuddy/skills/gmail/install.sh`
+- ✅ Review `SECURITY.md` for comprehensive security guidance
+- ⚠️ Extra caution on shared systems - other users may access your credentials if permissions are wrong!
+
+## Setup
+
+**Recommended**: Use the secure installation script:
+
+```bash
+cd .codebuddy/skills/gmail
+bash install.sh
+```
+
+This script will:
+
+- Create isolated Python virtual environment
+- Install dependencies with security audit
+- Set secure file permissions (700/600)
+- Guide you through OAuth2 setup
+
+**Manual Setup** (if needed):
+
+Before using, you must authenticate with Google OAuth2. Run the following command in the terminal:
+
+```bash
+./.codebuddy/bin/gmail-cli-wrapper auth
+```
+
+This will:
+
+1. Open a browser window for Google OAuth2 authentication
+2. Request permissions to access your Gmail account
+3. Store credentials locally for future use
+
+**Important**: You need to set up OAuth2 credentials first. See `SETUP.md` for detailed instructions.
+
+## Common Commands
+
+### Authentication
+
+- Authenticate: `./.codebuddy/bin/gmail-cli-wrapper auth`
+- Reset authentication: `./.codebuddy/bin/gmail-cli-wrapper auth --reset`
+
+### Reading Emails
+
+- List recent emails: `./.codebuddy/bin/gmail-cli-wrapper list --max 10`
+- List unread emails: `./.codebuddy/bin/gmail-cli-wrapper list --unread`
+- Search emails: `./.codebuddy/bin/gmail-cli-wrapper list --query "subject:meeting"`
+- Read specific email: `./.codebuddy/bin/gmail-cli-wrapper read <message-id>`
+
+### Sending Emails
+
+- Send email: `./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --subject "Hello" --body "Message text"`
+- Send with CC: `./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --cc "other@example.com" --subject "Hello" --body "Message"`
+- Send with attachment: `./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --subject "Files" --body "See attached" --attach /path/to/file.pdf`
+- Multiple attachments: `./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --subject "Files" --body "Documents" --attach file1.pdf file2.docx`
+
+## Search Query Examples
+
+Gmail CLI supports advanced search queries similar to Gmail's web interface:
+
+- `"from:john@example.com"` - Emails from a specific sender
+- `"subject:invoice"` - Emails with "invoice" in subject
+- `"has:attachment"` - Emails with attachments
+- `"is:unread"` - Unread emails
+- `"after:2024/01/01"` - Emails after a specific date
+- `"to:me cc:boss@company.com"` - Emails to you with CC to boss
+- `"newer_than:2d"` - Emails from last 2 days
+
+Example:
+
+```bash
+./.codebuddy/bin/gmail-cli-wrapper list --query "from:client@company.com subject:invoice has:attachment"
+```
+
+## Configuration
+
+Configuration and credentials are stored in:
+
+- `~/.gmail-cli/credentials.json` - OAuth2 credentials (from Google Cloud Console)
+- `~/.gmail-cli/token.pickle` - Access token (auto-generated and auto-refreshed)
+
+## Prerequisites
+
+Before using this tool, you need to:
+
+1. Install Python 3.7+
+2. Install required packages: `pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib`
+3. Set up OAuth2 credentials from Google Cloud Console (see SETUP.md)
+
+## 🔒 Security Best Practices
+
+### File Permissions (MANDATORY)
+
+```bash
+# Secure the credential directory
+chmod 700 ~/.gmail-cli
+
+# Secure credential files
+chmod 600 ~/.gmail-cli/credentials.json
+chmod 600 ~/.gmail-cli/token.pickle
+
+# Verify permissions
+ls -la ~/.gmail-cli/
+# Should show: drwx------ for directory, -rw------- for files
+```
+
+### Input Validation
+
+The secure implementation (`gmail-cli-secure.py`) validates all inputs:
+
+- ✅ Email addresses checked against RFC 5322 format
+- ✅ File paths validated to prevent path traversal
+- ✅ Sensitive files blocked from attachments
+- ✅ Text fields sanitized to prevent injection attacks
+
+### Safe Usage Example
+
+```bash
+# ✅ SAFE: Properly quoted and validated
+EMAIL="user@example.com"
+SUBJECT="Monthly Report"
+BODY="Please review"
+FILE="/path/to/document.pdf"
+
+# Validate before using
+[[ -f "$FILE" ]] || exit 1
+
+./.codebuddy/bin/gmail-cli-wrapper send --to "$EMAIL" --subject "$SUBJECT" \
+    --body "$BODY" --attach "$FILE"
+```
+
+### ❌ Unsafe Practices
+
+```bash
+# DON'T DO THIS: Never use untrusted input directly
+read -p "Enter recipient: " RECIPIENT
+./.codebuddy/bin/gmail-cli-wrapper send --to "$RECIPIENT" --subject "Test"
+
+# DON'T DO THIS: Sending sensitive files
+./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" \
+    --subject "Keys" --attach ~/.ssh/id_rsa  # ❌ DANGER!
+```
+
+## Notes
+
+- **OAuth2 Required**: You must complete OAuth2 authentication before using the tool
+- **Google Account Access**: Requires a Google account with Gmail enabled
+- **API Permissions**: Recommended scopes: `gmail.readonly` + `gmail.send` (NOT `gmail.modify`)
+- **Rate Limits**: Subject to Gmail API rate limits (usually sufficient for normal use)
+- **Security**: Tokens are stored locally in `~/.gmail-cli/`; must have 600 permissions
+- **First Time Setup**: Setup requires creating a Google Cloud project and OAuth2 credentials (see SETUP.md)
+- **Token Rotation**: Revoke tokens every 30-90 days or after device loss
+- **Shared Systems**: Extra caution on shared computers - use restrictive permissions!
+
+## Troubleshooting
+
+- **Authentication fails**: Try `./.codebuddy/bin/gmail-cli-wrapper auth --reset` to re-authenticate
+- **Package errors**: Install packages with `pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib`
+- **Credentials not found**: Make sure `~/.gmail-cli/credentials.json` exists (see SETUP.md)
+- **Permission denied**: Ensure the wrapper has execute permissions: `chmod +x ./.codebuddy/bin/gmail-cli-wrapper`
+
+## 📚 Documentation
+
+- **SECURITY.md** - 🔒 **READ THIS FIRST** - Comprehensive security guide
+- **SETUP.md** - Detailed setup instructions with Google Cloud Console configuration
+- **README.md** - Quick start guide and feature overview
+- **gmail-cli-secure.py** - Reference implementation with input validation
+- **email/skill.md** - Alternative SMTP-based email sending (simpler but less features)
+
+## 🛡️ Security Checklist
+
+Before using Gmail CLI, verify:
+
+- [ ] Installed using `install.sh` script (virtual environment + security audit)
+- [ ] `~/.gmail-cli/` has 700 permissions
+- [ ] `credentials.json` has 600 permissions
+- [ ] `token.pickle` has 600 permissions
+- [ ] `.gitignore` configured to exclude sensitive files
+- [ ] Using minimal OAuth2 scopes (readonly + send, NOT modify)
+- [ ] Read SECURITY.md for best practices
+- [ ] Understand how to revoke tokens if compromised

package/dist/skills/jira/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: jira
+description: Manage Jira issues, sprints, and epics via the jira-cli tool.
+metadata:
+  displayName: Jira
+  icon: jira
+  category: project-management
+  version: 1.0.0
+  dependencies:
+    cli: jira
+    checkCommand: jira version
+    install:
+      darwin:
+        brew: ankitpokhrel/jira-cli/jira-cli
+        script: curl -fsSL https://raw.githubusercontent.com/ankitpokhrel/jira-cli/master/scripts/install.sh | sh
+      linux:
+        script: curl -fsSL https://raw.githubusercontent.com/ankitpokhrel/jira-cli/master/scripts/install.sh | sh
+      windows:
+        scoop: jira-cli
+  config:
+    - name: JIRA_API_TOKEN
+      label: API Token
+      type: secret
+      required: true
+      helpUrl: https://id.atlassian.com/manage-profile/security/api-tokens
+    - name: JIRA_BASE_URL
+      label: Jira Base URL
+      type: string
+      required: true
+      placeholder: https://yourcompany.atlassian.net
+  auth:
+    type: api-key
+    setupCommand: jira init
+---
+
+# jira-cli
+
+Use `./.codebuddy/bin/jira` to interact with Jira.
+This tool allows you to view, create, and update Jira issues directly from the chat.
+
+## Setup
+
+Before using, you must authenticate. Run the following command in the terminal:
+`./.codebuddy/bin/jira init`
+
+## Common Commands
+
+### Issues
+
+- List issues: `./.codebuddy/bin/jira issue list`
+- View issue: `./.codebuddy/bin/jira issue view <ISSUE-KEY>`
+- Create issue: `./.codebuddy/bin/jira issue create`
+- Comment: `./.codebuddy/bin/jira issue comment add <ISSUE-KEY> "Comment text"`
+- Assign: `./.codebuddy/bin/jira issue assign <ISSUE-KEY> <USER>`
+
+### Sprints & Boards
+
+- List boards: `./.codebuddy/bin/jira board list`
+- List sprints: `./.codebuddy/bin/jira sprint list --board <BOARD-ID>`
+
+### JQL
+
+- Search with JQL: `./.codebuddy/bin/jira issue list --jql "project = PROJ AND status = 'In Progress'"`
+
+## Notes
+
+- Ensure you have an API token ready from Atlassian (https://id.atlassian.com/manage-profile/security/api-tokens).
+- Configuration is stored in `~/.jira/.config.yml`.