From e21b81baef5df6ca7812f41ac0eb4eba7a6d355b Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Mon, 6 Apr 2026 17:18:31 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20docs:=20add=20comprehensive=20re?= =?UTF-8?q?ference=20guide=20and=20update=20to=20kebab-case=20(related=20t?= =?UTF-8?q?o=20#2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vibe/skills/gitea-client/REFERENCE.md | 308 ++++++++++++++++++ .../gitea-client/scripts/gitea-client.sh | 2 +- AGENT_CHANGELOG.md | 44 ++- README.md | 10 +- 4 files changed, 356 insertions(+), 8 deletions(-) create mode 100644 .vibe/skills/gitea-client/REFERENCE.md diff --git a/.vibe/skills/gitea-client/REFERENCE.md b/.vibe/skills/gitea-client/REFERENCE.md new file mode 100644 index 0000000..b6ae3ec --- /dev/null +++ b/.vibe/skills/gitea-client/REFERENCE.md @@ -0,0 +1,308 @@ +# 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 [limit] + +# Check specific job status +gitea-client job-status + +# Fetch job logs for debugging +gitea-client job-logs [output_file] + +# List all jobs in a workflow run +gitea-client list-workflow-jobs + +# Wait for job completion +gitea-client wait-job [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 + +# Add comment to PR +gitea-client comment-pr +``` + +**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 [state] + +# Create new issue +gitea-client create-issue <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. \ No newline at end of file diff --git a/.vibe/skills/gitea-client/scripts/gitea-client.sh b/.vibe/skills/gitea-client/scripts/gitea-client.sh index ee01409..a4be43c 100755 --- a/.vibe/skills/gitea-client/scripts/gitea-client.sh +++ b/.vibe/skills/gitea-client/scripts/gitea-client.sh @@ -95,7 +95,7 @@ cmd_job_logs() { exit 1 fi - local endpoint="/repos/${owner}/${repo}/actions/runs/${job_id}/logs" + local endpoint="/repos/${owner}/${repo}/actions/jobs/${job_id}/logs" local logs=$(api_request "GET" "$endpoint") if [[ -n "$output_file" ]]; then diff --git a/AGENT_CHANGELOG.md b/AGENT_CHANGELOG.md index 2b42d59..678515a 100644 --- a/AGENT_CHANGELOG.md +++ b/AGENT_CHANGELOG.md @@ -124,14 +124,34 @@ gitea-client create-issue arcodange DanceLessonsCoach "Issue Title" "Detailed de **Commit:** `a5f652f` **Message:** `🔧 refactor: replace 4 workflows with single optimized ci-cd.yaml (related to #2)` -**Web UI:** https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/issues/2 +**Web UI:** https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/2 **Validation Workflow:** - **Run ID:** 365 - **Status:** in_progress -- **URL:** https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/17 +- **URL:** https://gitea.arcodange.lab/arcodange/dance-lessons-coach/actions/runs/17 - **Workflow:** ci-cd.yaml (single unified workflow) +### Project Renaming + +**Change:** Updated git remote to use kebab-case + +**Before:** +``` +ssh://git@192.168.1.202:2222/arcodange/DanceLessonsCoach.git +``` + +**After:** +``` +ssh://git@192.168.1.202:2222/arcodange/dance-lessons-coach.git +``` + +**Impact:** +- ✅ Repository URL now uses kebab-case (hyphen-separated) +- ✅ Matches modern naming conventions +- ✅ Consistent with Gitea server configuration +- ✅ No functional changes (same repository, new URL) + ### TRUE Workflow Optimization (Replaced 4 workflows with 1) **Problem Identified:** @@ -202,6 +222,26 @@ gitea-client create-issue arcodange DanceLessonsCoach "Issue Title" "Detailed de - ✅ Easier to reference skills - ✅ Better organization +### Comprehensive Reference Guide + +**Created:** `.vibe/skills/gitea-client/REFERENCE.md` + +**Content:** +- 📋 Job monitoring use cases +- 🔧 PR management examples +- 📝 Issue tracking workflows +- 🎯 Real-world scenarios with copy-paste commands +- 🔧 Advanced patterns and best practices +- 📋 Complete command reference table + +**Purpose:** +- ✅ Onboard new developers quickly +- ✅ Provide real-world examples +- ✅ Document best practices +- ✅ Serve as living documentation + +**Size:** 9.1KB of comprehensive documentation + **Validation Status:** ⏳ IN PROGRESS - ✅ Commit pushed: `a5f652f` - ✅ Single workflow triggered: Run #365 diff --git a/README.md b/README.md index 5baac99..a3949f8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # DanceLessonsCoach -[![Build Status](https://gitea.arcodange.fr/api/badges/arcodange/DanceLessonsCoach/status)](https://gitea.arcodange.fr/arcodange/DanceLessonsCoach) -[![Go Report Card](https://goreportcard.com/badge/github.com/arcodange/DanceLessonsCoach)](https://goreportcard.com/report/github.com/arcodange/DanceLessonsCoach) -[![Version](https://img.shields.io/badge/version-1.1.1-blue.svg)](https://gitea.arcodange.fr/arcodange/DanceLessonsCoach/releases) +[![Build Status](https://gitea.arcodange.fr/api/badges/arcodange/dance-lessons-coach/status)](https://gitea.arcodange.fr/arcodange/dance-lessons-coach) +[![Go Report Card](https://goreportcard.com/badge/github.com/arcodange/dance-lessons-coach)](https://goreportcard.com/report/github.com/arcodange/dance-lessons-coach) +[![Version](https://img.shields.io/badge/version-1.1.1-blue.svg)](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/releases) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) A Go project demonstrating idiomatic package structure, CLI implementation, and JSON API with Chi router. @@ -27,8 +27,8 @@ A Go project demonstrating idiomatic package structure, CLI implementation, and ```bash # Clone the repository -git clone https://github.com/yourusername/DanceLessonsCoach.git -cd DanceLessonsCoach +git clone https://gitea.arcodange.lab/arcodange/dance-lessons-coach.git +cd dance-lessons-coach # Build all binaries ./scripts/build.sh