Plugin Directory

Automated plugin registry with PR validation and auto-merge capabilities for the Plugin Host system.

Features

  • 🤖 Automated PR Processing: Automatically validates and merges plugin submissions
  • ✅ Strict Validation: Enforces plugin schema and ownership rules
  • 🔒 Ownership Protection: Users can only remove plugins they authored
  • 📡 Webhook Integration: Gitea webhook support for real-time PR handling
  • 🔍 Schema Validation: Ensures all plugins meet quality standards
  • 📦 REST API: List and query available plugins

Setup

1. Install Dependencies

npm install

2. Configure Environment

Copy .env.example to .env and fill in your Gitea details:

cp .env.example .env

Edit .env:

GITEA_URL=http://synbox.ruv.wtf:8418
GITEA_TOKEN=your_gitea_access_token_here
WEBHOOK_SECRET=your_webhook_secret_here
PORT=3000

3. Configure Gitea Webhook

In your Gitea repository settings:

  1. Go to Settings → Webhooks → Add Webhook → Gitea
  2. Set Payload URL: http://your-server:3000/webhook
  3. Set Secret: (same as WEBHOOK_SECRET in .env)
  4. Select events: Pull Request
  5. Save webhook

4. Start Server

npm start

For development with auto-reload:

npm run dev

Plugin Submission Rules

Valid PRs Must:

  1. ✅ Only modify files in the plugins/ directory
  2. ✅ Only add or remove .json files
  3. ✅ Have valid JSON matching the plugin schema
  4. ✅ Have plugin ID matching the filename
  5. ✅ Have author field matching PR author (for new plugins)
  6. ✅ Only remove plugins you authored

Plugin Schema

{
  "id": "your-plugin-id",
  "name": "Your Plugin Name",
  "version": "1.0.0",
  "description": "What your plugin does",
  "author": "your-gitea-username",
  "repository": "http://synbox.ruv.wtf:8418/username/plugin-repo.git",
  "downloadUrl": "http://synbox.ruv.wtf:8418/username/plugin-repo/archive/main.zip",
  "homepage": "http://synbox.ruv.wtf:8418/username/plugin-repo",
  "tags": ["tag1", "tag2"],
  "addedDate": "2026-04-17T00:00:00.000Z"
}

Required Fields:

  • id - Unique identifier (must match filename without .json)
  • name - Display name
  • version - Semantic version (X.Y.Z)
  • description - What the plugin does
  • author - Your Gitea username
  • repository - Git repository URL

Optional Fields:

  • downloadUrl - Direct download link
  • homepage - Plugin homepage or docs
  • tags - Array of category tags
  • addedDate - ISO 8601 date string
  • dependencies - Required plugins or packages

API Endpoints

List All Plugins

GET /plugins

Response:

{
  "plugins": [...],
  "count": 10
}

Get Specific Plugin

GET /plugins/:pluginId

Health Check

GET /health

Webhook Endpoint

POST /webhook

How It Works

  1. User creates a PR adding/removing a plugin JSON file
  2. Gitea sends webhook to the directory server
  3. Server validates the PR:
    • Checks file locations
    • Validates JSON schema
    • Verifies ownership for removals
    • Ensures author matches PR creator
  4. If valid: Auto-approves and merges
  5. If invalid: Comments with error details

Undoing Changes

To undo a merged plugin submission:

  1. Create a new PR that reverses the change
  2. To remove a plugin you added: delete the JSON file
  3. To re-add a plugin you removed: add the JSON file back

The same validation rules apply - you can only remove plugins you authored.

Development

The system consists of:

  • server.js - Express server and endpoints
  • WebhookHandler.js - Processes Gitea webhooks
  • ValidatorEnhanced.js - Validates PR changes
  • plugins/ - Plugin registry JSON files

Security

  • Webhook signatures are verified using HMAC-SHA256
  • Only PR authors can modify their own plugins
  • All file operations are restricted to the plugins/ directory
  • JSON parsing errors are caught and reported

License

MIT

S
Description
No description provided
Readme
186 KiB
Languages
JavaScript 100%