Initial commit

2025-11-30 08:49:38 +08:00
commit 6c0d5ab58d
4 changed files with 371 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,314 @@
+# Setup Marketplace Sync
+
+## Skill Metadata
+- version: "1.2.0"
+- description: "Configure automated Claude Code marketplace synchronization in your repository"
+- author: "Claude Code Marketplace Aggregator"
+
+## Overview
+
+This skill helps you set up automated synchronization of Claude Code plugins from multiple marketplaces into your own aggregated marketplace. It handles both GitHub Actions and GitLab CI/CD pipelines, including automated scheduling setup.
+
+## Instructions for Claude Code
+
+When this skill is invoked, follow these steps carefully:
+
+### Step 1: Gather User Requirements
+
+Use the `AskUserQuestion` tool to collect the following information:
+
+1. **Platform**: Ask whether the user is using GitHub or GitLab
+   - Options: "GitHub", "GitLab"
+
+2. **Marketplaces to sync**: Ask for a list of marketplace repositories to sync from
+   - Explain: "Enter the Git URLs of marketplaces you want to sync plugins from (e.g., https://github.com/org/marketplace-repo)"
+   - Allow multiple entries
+   - For each marketplace, ask:
+     - Repository URL (required)
+     - Branch name (default: "main")
+     - Tag prefix for origin tracking (e.g., "enterprise/engineering")
+     - Any plugins to denylist (comma-separated names)
+
+3. **Local skills**: Ask if they want to include any local skill directories
+   - If yes, collect:
+     - Skill directory path (relative to repo root)
+     - Skill name
+     - Skill description
+
+4. **For GitLab only**:
+   - GitLab runner tags (REQUIRED) - Ask: "What GitLab runner tags should be used? (e.g., 'docker', 'linux', 'shared'). If unsure, check your GitLab project's Settings → CI/CD → Runners to see available tags."
+   - GitLab server URL (default: "https://gitlab.com")
+   - Project ID or namespace/project-name
+   - GitLab access token (PAT) - explain it needs `api` scope
+   - Schedule preference (default: "0 2 * * *" - 2 AM daily)
+
+### Step 2: Search for Existing Configuration
+
+Use the `Glob` tool to search for existing sync configuration:
+
+```
+pattern: "**/.sync-config.json"
+```
+
+If found:
+- Read the file using the `Read` tool
+- Ask user: "Found existing .sync-config.json at {path}. Would you like to update it or create a new one?"
+- If update: merge new sources with existing ones (avoid duplicates)
+
+If not found:
+- Proceed to create new configuration
+
+### Step 3: Create or Update .sync-config.json
+
+Create the configuration file at the repository root with this structure:
+
+```json
+{
+  "marketplace": {
+    "name": "My Aggregated Marketplace",
+    "description": "Aggregated Claude Code plugins from multiple sources",
+    "author": "Your Organization",
+    "homepage": "https://github.com/your-org/your-repo"
+  },
+  "sources": [
+    {
+      "type": "marketplace",
+      "url": "https://github.com/source-org/source-marketplace",
+      "branch": "main",
+      "tag_prefix": "source-name",
+      "denylist": []
+    }
+  ],
+  "sync_settings": {
+    "exclude_patterns": [
+      ".git",
+      "*.pyc",
+      "__pycache__",
+      ".pytest_cache"
+    ]
+  }
+}
+```
+
+**Important**:
+- Populate `marketplace` metadata with sensible defaults or user-provided values
+- Add each marketplace source from user input to the `sources` array
+- For local skills, add entries with `"type": "skill"` and the local path
+- Ensure JSON is valid and properly formatted
+
+### Step 4: Set Up CI/CD Pipeline
+
+#### For GitHub:
+
+1. Create `.github/workflows/sync-marketplace.yml`:
+
+```yaml
+name: Sync Marketplace
+
+on:
+  schedule:
+    # Run daily at 2 AM UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: ralphbean/claude-marketplace-sync@main
+        with:
+          config-path: '.sync-config.json'
+          verbose: 'true'
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          if [[ -n $(git status --porcelain) ]]; then
+            git add .claude-plugin/
+            git commit -m "chore: sync marketplace plugins
+
+            🤖 Automated sync from configured marketplace sources"
+            git push
+          else
+            echo "No changes to commit"
+          fi
+```
+
+2. Inform the user:
+   - "✓ Created GitHub Actions workflow at .github/workflows/sync-marketplace.yml"
+   - "The workflow will run daily at 2 AM UTC and can be triggered manually"
+   - "No additional setup needed - GitHub Actions is ready to go!"
+
+#### For GitLab:
+
+1. Create `.gitlab-ci.yml`:
+
+```yaml
+# Include the reusable sync template from the marketplace-sync repository
+include:
+  - remote: 'https://raw.githubusercontent.com/ralphbean/claude-marketplace-sync/main/.gitlab-ci-template.yml'
+
+# Configure sync behavior (optional - these are the defaults)
+variables:
+  SYNC_CONFIG_PATH: ".sync-config.json"
+  SYNC_OUTPUT_PATH: ".claude-plugin/marketplace.json"
+  SYNC_VERBOSE: "true"
+
+# Specify your GitLab runner tags (REQUIRED)
+sync-marketplace:
+  tags:
+    - <REPLACE_WITH_USER_PROVIDED_TAGS>
+```
+
+**Important**: Replace `<REPLACE_WITH_USER_PROVIDED_TAGS>` with the actual tags provided by the user. If the user provided multiple tags (comma-separated), create a list entry for each tag. For example, if user provided "docker,linux", generate:
+
+```yaml
+sync-marketplace:
+  tags:
+    - docker
+    - linux
+```
+
+2. **Attempt automated setup via GitLab API**:
+
+   Use the `Bash` tool to attempt the following:
+
+   a. **Set CI/CD variable for GITLAB_TOKEN**:
+   ```bash
+   curl --request POST \
+     --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
+     "${GITLAB_URL}/api/v4/projects/${PROJECT_ID}/variables" \
+     --form "key=GITLAB_TOKEN" \
+     --form "value=${GITLAB_TOKEN}" \
+     --form "protected=false" \
+     --form "masked=true"
+   ```
+
+   b. **Create pipeline schedule**:
+   ```bash
+   curl --request POST \
+     --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
+     "${GITLAB_URL}/api/v4/projects/${PROJECT_ID}/pipeline_schedules" \
+     --form "description=Daily marketplace sync" \
+     --form "ref=main" \
+     --form "cron=0 2 * * *" \
+     --form "cron_timezone=UTC" \
+     --form "active=true"
+   ```
+
+3. **Handle API results**:
+
+   - If successful (HTTP 200/201): Inform user that setup is complete
+   - If failed (HTTP 401/403 - insufficient permissions): Provide manual instructions below
+   - If failed (other error): Show error and provide manual instructions
+
+4. **Manual setup instructions** (provide if API fails):
+
+```
+⚠️  Automated setup failed. Please complete these steps manually:
+
+1. Set up GitLab CI/CD Variable:
+   - Go to: Settings → CI/CD → Variables
+   - Click "Add variable"
+   - Key: GITLAB_TOKEN
+   - Value: [your GitLab PAT with 'api' and 'write_repository' scopes]
+   - Flags: Check "Mask variable"
+   - Click "Add variable"
+
+2. Create Pipeline Schedule:
+   - Go to: CI/CD → Schedules
+   - Click "New schedule"
+   - Description: "Daily marketplace sync"
+   - Interval Pattern: Custom (0 2 * * *)
+   - Cron timezone: UTC
+   - Target branch: main
+   - Click "Save pipeline schedule"
+
+3. Token Requirements:
+   Your GitLab Personal Access Token needs these scopes:
+   - ✓ api (full API access)
+   - ✓ write_repository (push changes)
+
+   To create a token:
+   - Go to: User Settings → Access Tokens
+   - Name: "Marketplace Sync"
+   - Expiration: Set as needed
+   - Select scopes: api, write_repository
+   - Click "Create personal access token"
+   - Copy the token (you won't see it again!)
+
+4. Test the Pipeline:
+   - Go to: CI/CD → Schedules
+   - Click the play button (▶) next to your schedule
+   - Monitor: CI/CD → Pipelines
+```
+
+### Step 5: Create README Documentation
+
+Create or update a `MARKETPLACE-SYNC.md` file with:
+- Overview of the sync setup
+- List of configured marketplace sources
+- How to manually trigger sync (GitHub: Actions tab, GitLab: Schedules)
+- How to add new marketplace sources (edit .sync-config.json)
+- How to denylist plugins (add to denylist array)
+
+### Step 6: Final Summary
+
+Provide a concise summary:
+
+```
+✅ Marketplace sync setup complete!
+
+Configuration:
+- Platform: [GitHub/GitLab]
+- Marketplaces: [count] configured
+- Local skills: [count] included
+- Schedule: Daily at 2 AM UTC
+
+Next steps:
+1. Review .sync-config.json to verify sources
+2. [For GitLab] Complete manual setup steps above if needed
+3. Commit these changes to your repository
+4. [Platform-specific] The first sync will run on schedule or can be triggered manually
+
+Files created/updated:
+- .sync-config.json
+- [.github/workflows/sync-marketplace.yml OR .gitlab-ci.yml]
+- MARKETPLACE-SYNC.md
+
+The sync will generate:
+- .claude-plugin/marketplace.json (aggregated marketplace)
+- .claude-plugin/origins.json (plugin origin tracking)
+```
+
+## Error Handling
+
+- If any git commands fail, provide clear error messages
+- If API calls fail, always fall back to manual instructions
+- If configuration file is malformed, validate and fix JSON syntax
+- If paths don't exist, create necessary directories
+- Always verify token permissions before attempting automated setup
+
+## Testing Recommendations
+
+After setup, suggest the user:
+1. Manually trigger the pipeline to test it works
+2. Verify .claude-plugin/marketplace.json is generated correctly
+3. Check that origins.json tracks sources properly
+4. Review pipeline logs for any warnings
+
+## Notes
+
+- This skill does NOT commit changes automatically - let the user review first
+- For GitLab, token security is critical - always mask the variable
+- The sync runs in a clone of the repo, so local paths in config must be relative
+- Diamond dependencies (same plugin from multiple sources) are handled automatically