base version (design by sunrisepeak / write by claude-code)

Author: Sunrisepeak

.github/workflows/daily-scan.yml

@@ -0,0 +1,52 @@
+name: Daily Bot Tasks
+
+on:
+  schedule:
+    # Run daily at 02:00 China Time (18:00 UTC)
+    - cron: "0 18 * * *"
+  # Allow manual trigger
+  workflow_dispatch:
+    inputs:
+      components:
+        description: 'Components to run (all, join-issues, task-checker)'
+        required: false
+        default: 'all'
+        type: choice
+        options:
+          - all
+          - join-issues
+          - task-checker
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  run-bot:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Create GitHub App installation token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          owner: mcpp-community
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Run MCPP Bot
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          # Determine which components to run
+          COMPONENTS="${{ github.event.inputs.components || 'all' }}"
+
+          echo "Running MCPP Bot with components: $COMPONENTS"
+          python src/main.py $COMPONENTS --verbose

LICENSE

@@ -1,3 +1,7 @@
+Copyright (c) 2026-present mcpp community, speakshen@163.com
+
+---
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

README.md

@@ -1 +1,115 @@
-# mcpp-bot
+# MCPP Bot
+
+A collection of GitHub automation tools for managing repositories and organizations.
+
+## Project Structure
+
+```
+src/
+├── components/         # Bot components and modules
+│   ├── scan_join_issues.py    # Process join requests
+│   ├── task_checker.py         # Check and remind on overdue tasks
+│   └── README.md               # Component documentation
+├── config/            # Configuration files
+│   ├── join-config.yml        # Join request configuration
+│   └── task-checker.yml       # Task checker configuration
+├── libs/              # Shared libraries
+│   ├── github_client.py       # GitHub API client
+│   ├── utils.py               # Utility functions
+│   └── __init__.py
+└── main.py            # Main entry point
+```
+
+## Components
+
+### 1. Task Checker
+
+Monitors task issues with priority labels (P0/P1/P2) and sends reminders when they haven't been updated within configured timeouts.
+
+**Quick Start:**
+```bash
+export GH_TOKEN="your_github_token"
+python src/components/task_checker.py
+```
+
+**Features:**
+- Scan single repository or entire organization
+- Customizable timeout thresholds per priority (P0/P1/P2)
+- Flexible reminder templates
+- Repository exclusion support
+- Configurable priority patterns
+
+See [components/README.md](src/components/README.md) for detailed configuration options.
+
+### 2. Join Request Scanner
+
+Processes join request issues for organization membership management.
+
+**Quick Start:**
+```bash
+export GH_TOKEN="your_github_token"
+python src/components/scan_join_issues.py
+```
+
+## Quick Start
+
+1. Clone the repository
+2. Set up your GitHub token:
+   ```bash
+   export GH_TOKEN="your_github_personal_access_token"
+   ```
+3. Configure the components in `src/config/`
+4. Run the bot:
+   ```bash
+   # Run all components
+   python src/main.py all
+
+   # Run specific component
+   python src/main.py join-issues
+   python src/main.py task-checker
+
+   # Run multiple components
+   python src/main.py join-issues task-checker
+
+   # Enable verbose error output
+   python src/main.py all --verbose
+   ```
+
+## Running Individual Components
+
+You can also run components directly:
+
+```bash
+# Task checker
+python src/components/task_checker.py
+
+# Join issues scanner
+python src/components/scan_join_issues.py
+```
+
+## Configuration
+
+All components use YAML configuration files in `src/config/`:
+
+- `join-config.yml` - Join request processing settings
+- `task-checker.yml` - Task monitoring and reminder settings
+
+## Requirements
+
+- Python 3.7+
+- GitHub Personal Access Token with appropriate permissions
+  - For task checker: `repo` scope (read issues, write comments)
+  - For join scanner: `admin:org` scope (manage organization members)
+
+## GitHub Actions Workflows
+
+This project includes automated workflows for scheduled execution:
+
+- **Daily Bot Tasks** (`daily-scan.yml`): Runs all components daily at 02:20 UTC
+- **Task Checker Hourly** (`task-checker-hourly.yml`): Checks task timeouts every 6 hours
+
+See [.github/workflows/README.md](.github/workflows/README.md) for workflow documentation.
+
+## License
+
+See [LICENSE](LICENSE) for details.

src/components/README.md

@@ -0,0 +1,78 @@
+# Components
+
+This directory contains various bot components for managing GitHub repositories and organizations.
+
+## Available Components
+
+### 1. scan_join_issues.py
+
+Scans and processes join request issues for organization membership.
+
+**Usage:**
+```bash
+export GH_TOKEN="your_github_token"
+python src/components/scan_join_issues.py
+```
+
+**Configuration:** `config/join-config.yml`
+
+### 2. task_checker.py
+
+Scans for task issues with priority labels (P0/P1/P2) and sends reminders if they haven't been updated within configured timeouts.
+
+**Usage:**
+```bash
+export GH_TOKEN="your_github_token"
+python src/components/task_checker.py
+```
+
+**Configuration:** `config/task-checker.yml`
+
+**Features:**
+- Flexible scan modes: single repository or entire organization
+- Customizable timeout thresholds for P0/P1/P2 priorities
+- Customizable reminder message template
+- Repository exclusion support
+- Optional reminders for unassigned tasks
+
+**Configuration Options:**
+
+- `scan_mode`: Set to `"repo"` for single repository or `"org"` for organization-wide scanning
+- `timeout_hours`: Configure different timeout thresholds for each priority level
+  - `P0`: High priority tasks (default: 24 hours)
+  - `P1`: Medium priority tasks (default: 72 hours)
+  - `P2`: Low priority tasks (default: 168 hours)
+- `priorities_to_check`: Limit which priorities to scan (e.g., only P0 and P1)
+- `exclude_repos`: Exclude specific repositories when scanning an organization
+- `task_label`: Customize the label that identifies task issues (default: "Task")
+- `priority_pattern`: Regex pattern to match priority labels
+- `reminder_template`: Customize the reminder message format
+- `notify_unassigned`: Whether to send reminders for tasks without assignees
+- `default_mention`: Default mentions for unassigned tasks (can be string or list)
+
+**Example Scenarios:**
+
+1. **Scan single repository:**
+   ```yaml
+   scan_mode: repo
+   repo: mcpp-community/mcpp-bot
+   ```
+
+2. **Scan entire organization:**
+   ```yaml
+   scan_mode: org
+   org: mcpp-community
+   exclude_repos:
+     - archived-project
+   ```
+
+3. **Only check critical tasks (P0):**
+   ```yaml
+   priorities_to_check: ["P0"]
+   timeout_hours:
+     P0: 12  # Alert after 12 hours
+   ```
+
+## Common Configuration
+
+All components use configuration files in the `config/` directory and require a GitHub token via the `GH_TOKEN` environment variable.

src/components/scan_join_issues.py

@@ -0,0 +1,81 @@
+import json
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path to import from libs
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from libs.github_client import (
+    comment,
+    close_issue,
+    has_label,
+    get_target_from_labels,
+    is_org_member,
+    add_user_to_team,
+    is_user_in_team,
+    list_open_join_issues,
+)
+from libs.utils import load_simple_yaml
+
+def scan():
+    # Load configuration first
+    cfg = load_simple_yaml("config/join-config.yml")
+
+    # Get token from environment variable
+    token = os.environ.get("GH_TOKEN", "").strip()
+
+    # Get org and repo from config file
+    org = cfg.get("org", "").strip()
+    repo = cfg.get("repo", "").strip()
+
+    if not token:
+        raise ValueError("Environment variable GH_TOKEN is not set or empty")
+    if not org:
+        raise ValueError("Organization (org) is not set in config file config/join-config.yml")
+    if not repo:
+        raise ValueError("Repository (repo) is not set in config file config/join-config.yml")
+
+    teams_cfg = cfg.get("teams") or {}
+
+    issues = list_open_join_issues(token, repo)
+
+    for it in issues:
+        issue_number = it["number"]
+        author = it["user"]["login"]
+
+        target = get_target_from_labels(it)
+        if not target or target not in teams_cfg:
+            continue
+
+        team_cfg = teams_cfg[target]
+        team_slug = team_cfg.get("team_slug", "") or ""
+
+        # If not org member yet, remind and keep open
+        if not is_org_member(token, org, author):
+            if has_label(it, "invited"):
+                comment(token, repo, issue_number,
+                        f"@{author} 温馨提示：你还未加入 **@{org}**。请在这里接受邀请：\n\nhttps://github.com/orgs/{org}/invitation")
+            continue
+
+        # If needs team, ensure team membership
+        if team_slug:
+            if not is_user_in_team(token, org, team_slug, author):
+                code, payload = add_user_to_team(token, org, team_slug, author)
+                if code not in (200, 201):
+                    # Can't add team for some reason; leave a note and continue
+                    comment(token, repo, issue_number,
+                            f"@{author} 已检测到你已加入 **@{org}**，但加入 **@{org}/{team_slug}** 仍失败，将稍后重试。\n\n"
+                            f"HTTP {code}\n\n```json\n{json.dumps(payload, ensure_ascii=False, indent=2)}\n```")
+                    continue
+
+        # Now complete: comment + close
+        if team_slug:
+            comment(token, repo, issue_number, f"@{author} ✅ 已确认你已加入 **@{org}** 并加入 **@{org}/{team_slug}**，本 Issue 将关闭。")
+        else:
+            comment(token, repo, issue_number, f"@{author} ✅ 已确认你已加入 **@{org}**，本 Issue 将关闭。")
+
+        close_issue(token, repo, issue_number)
+
+if __name__ == "__main__":
+    scan()