dance-lessons-coach/.vibe/skills/gitea-client/REFERENCE.md

# Gitea-Client Skill Reference Guide

## 🎯 Overview

The Gitea-Client skill provides comprehensive API access to Gitea repositories, enabling job monitoring, PR management, and issue tracking directly from the command line.

## 📋 Use Cases

### 1. Job Monitoring and CI/CD Management

**Scenario:** Monitor CI/CD workflows and diagnose failures

**Commands:**
```bash
# List recent workflow jobs
gitea-client list-jobs <owner> <repo> <workflow_id> [limit]

# Check specific job status
gitea-client job-status <owner> <repo> <job_id>

# Fetch job logs for debugging
gitea-client job-logs <owner> <repo> <job_id> [output_file]

# List all jobs in a workflow run
gitea-client list-workflow-jobs <owner> <repo> <workflow_run_id>

# Wait for job completion
gitea-client wait-job <owner> <repo> <job_id> [timeout]
```

**Example Workflow:**
```bash
# 1. Find recent failed jobs
gitea-client list-jobs arcodange DanceLessonsCoach 5 10

# 2. Check status of specific job
gitea-client job-status arcodange DanceLessonsCoach 706

# 3. Fetch logs for debugging
gitea-client job-logs arcodange DanceLessonsCoach 706 job_706_logs.txt

# 4. Analyze logs
grep -i "error\|fail" job_706_logs.txt
```

### 2. Pull Request Management

**Scenario:** Monitor and comment on PRs during CI/CD

**Commands:**
```bash
# Check PR status
gitea-client pr-status <owner> <repo> <pr_number>

# Add comment to PR
gitea-client comment-pr <owner> <repo> <pr_number> <comment>
```

**Example Workflow:**
```bash
# Get PR number from branch
PR_NUMBER=$(gitea-client list-prs arcodange DanceLessonsCoach | jq -r '.[] | select(.head.ref == "feature/new-feature") | .number')

# Comment on PR with CI results
gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER "✅ CI passed: All checks successful!"
```

### 3. Issue Tracking

**Scenario:** Create and manage repository issues

**Commands:**
```bash
# List open issues
gitea-client list-issues <owner> <repo> [state]

# Create new issue
gitea-client create-issue <owner> <repo> <title> <description>

# Show issue details
gitea-client show-issue <owner> <repo> <issue_number>

# Comment on issue
gitea-client comment-issue <owner> <repo> <issue_number> <comment>
```

**Example Workflow:**
```bash
# Create issue for bug
gitea-client create-issue arcodange DanceLessonsCoach "CI Failure" "Workflow failed on job 706"

# Add progress comment
gitea-client comment-issue arcodange DanceLessonsCoach 42 "Investigating logs..."

# Resolve issue
gitea-client comment-issue arcodange DanceLessonsCoach 42 "✅ Fixed in commit abc123"
```

## 🎯 Real-World Examples

### Example 1: CI/CD Debugging Workflow

```bash
# Scenario: Job failed, need to diagnose

# 1. List recent jobs
gitea-client list-jobs arcodange DanceLessonsCoach 5 5

# 2. Find failed job
gitea-client job-status arcodange DanceLessonsCoach 706

# 3. Fetch logs
gitea-client job-logs arcodange DanceLessonsCoach 706 debug_logs.txt

# 4. Analyze
grep -i "error\|panic\|fail" debug_logs.txt

# 5. Comment on related PR
gitea-client comment-pr arcodange DanceLessonsCoach 15 "Found issue in CI - investigating"
```

### Example 2: Automated PR Feedback

```bash
# Scenario: CI job failed, auto-comment on PR

JOB_ID=706
PR_NUMBER=$(gitea-client list-prs arcodange DanceLessonsCoach | jq -r '.[] | select(.head.ref == "feature/new-api") | .number')

if [ -n "$PR_NUMBER" ]; then
    gitea-client job-logs arcodange DanceLessonsCoach $JOB_ID job_logs.txt
    ERRORS=$(grep -i "error\|fail" job_logs.txt | head -5)
    
    gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER "⚠️ CI Job Failed: $JOB_ID

🔍 Errors found:
$ERRORS

📊 Job Details: https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/17/jobs/0"
fi
```

### Example 3: Issue Management Workflow

```bash
# Scenario: Feature implementation with issue tracking

# 1. Create issue for new feature
gitea-client create-issue arcodange DanceLessonsCoach "Add user authentication" "Implement OAuth2 authentication for API"

# 2. Work on feature, add progress comments
gitea-client comment-issue arcodange DanceLessonsCoach 42 "⏳ IN PROGRESS: Implementing OAuth2 provider"

# 3. Complete feature
gitea-client comment-issue arcodange DanceLessonsCoach 42 "✅ COMPLETED: Authentication implemented in commit abc123"

# 4. Reference in commit
git commit -m "✨ feat: add OAuth2 authentication (closes #42)"
```

## 🔧 Advanced Patterns

### Monitoring Multiple Jobs

```bash
# Watch multiple jobs in parallel
for job_id in 706 707 708; do
    gitea-client job-status arcodange DanceLessonsCoach $job_id &
done
wait
```

### Automated Issue Creation

```bash
# Create issue from CI when tests fail
if [ "$CI_JOB_STATUS" = "failed" ]; then
    gitea-client create-issue arcodange DanceLessonsCoach \
        "CI Failure: $CI_JOB_NAME" \
        "Job failed on commit $CI_COMMIT_SHA. See logs: $CI_JOB_URL"
fi
```

### Batch Issue Updates

```bash
# Update multiple issues with same comment
for issue in 42 43 44; do
    gitea-client comment-issue arcodange DanceLessonsCoach $issue "Status update: Related to PR #15"
done
```

## 📖 Best Practices

### 1. Always Check Job Status First
```bash
# Before commenting, verify job status
gitea-client job-status arcodange DanceLessonsCoach 706
```

### 2. Use Descriptive Issue Titles
```bash
# Good
gitea-client create-issue arcodange DanceLessonsCoach "API Authentication Failure" "Detailed description..."

# Bad
gitea-client create-issue arcodange DanceLessonsCoach "Bug" "Doesn't work"
```

### 3. Reference Issues in Commits
```bash
# Link commits to issues
git commit -m "🐛 fix: resolve auth bug (closes #42)"
```

### 4. Use Web UI Links
```bash
# Include links in comments
gitea-client comment-pr arcodange DanceLessonsCoach 15 "See: https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/issues/42"
```

## 🎯 Integration Patterns

### CI/CD Pipeline Integration

```yaml
# Example GitHub Actions step
- name: Comment on PR if tests fail
  if: failure()
  run: |
    PR_NUMBER=$(gitea-client list-prs owner repo | jq -r ".[] | select(.head.ref == '\${{ github.ref_name }}') | .number")
    if [ -n "$PR_NUMBER" ]; then
      gitea-client comment-pr owner repo $PR_NUMBER "❌ Build failed: \${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
    fi
```

### Automated Issue Tracking

```bash
# Script to create issues from errors
ERRORS=$(grep -i "error" app.log | head -5)
if [ -n "$ERRORS" ]; then
    gitea-client create-issue arcodange DanceLessonsCoach \
        "Production Errors Detected" \
        "Found errors in production logs:\n\n$ERRORS"
fi
```

## 💡 Tips and Tricks

### 1. Save Logs for Later Analysis
```bash
gitea-client job-logs arcodange DanceLessonsCoach 706 job_706_$(date +%Y%m%d).txt
```

### 2. Monitor Job Progress
```bash
watch -n 10 "gitea-client job-status arcodange DanceLessonsCoach 706"
```

### 3. Script Complex Workflows
```bash
#!/bin/bash
# monitor_and_comment.sh
JOB_ID=$1
PR_NUMBER=$2

STATUS=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.status')
if [ "$STATUS" = "completed" ]; then
    CONCLUSION=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.conclusion')
    if [ "$CONCLUSION" = "failure" ]; then
        gitea-client job-logs arcodange DanceLessonsCoach $JOB_ID logs.txt
        ERRORS=$(grep -i "error" logs.txt | head -3)
        gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER "❌ Job failed: $ERRORS"
    fi
fi
```

## 🔗 API Reference

All commands use the Gitea REST API v1:
- **Base URL**: `https://gitea.arcodange.lab/api/v1`
- **Authentication**: Personal Access Token (required)
- **Documentation**: https://gitea.com/api/swagger

## 📋 Command Reference

| Command | Description | Usage |
|---------|-------------|-------|
| `list-jobs` | List workflow jobs | `gitea-client list-jobs <owner> <repo> <workflow_id> [limit]` |
| `job-status` | Get job status | `gitea-client job-status <owner> <repo> <job_id>` |
| `job-logs` | Fetch job logs | `gitea-client job-logs <owner> <repo> <job_id> [output_file]` |
| `list-workflow-jobs` | List jobs in workflow | `gitea-client list-workflow-jobs <owner> <repo> <workflow_run_id>` |
| `wait-job` | Wait for job completion | `gitea-client wait-job <owner> <repo> <job_id> [timeout]` |
| `comment-pr` | Comment on PR | `gitea-client comment-pr <owner> <repo> <pr_number> <comment>` |
| `pr-status` | Get PR status | `gitea-client pr-status <owner> <repo> <pr_number>` |
| `list-issues` | List repository issues | `gitea-client list-issues <owner> <repo> [state]` |
| `create-issue` | Create new issue | `gitea-client create-issue <owner> <repo> <title> <description>` |
| `show-issue` | Show issue details | `gitea-client show-issue <owner> <repo> <issue_number>` |
| `comment-issue` | Comment on issue | `gitea-client comment-issue <owner> <repo> <issue_number> <comment>` |

## 🎓 Learning Resources

- **Gitea API Docs**: https://gitea.com/api/swagger
- **GitHub Actions**: https://docs.github.com/en/actions
- **JQ Tutorial**: https://stedolan.github.io/jq/manual/

This reference guide provides comprehensive examples for using the gitea-client skill in real-world scenarios, covering job monitoring, PR management, and issue tracking with practical, copy-paste-ready examples.