Plugin-Directory/README.md

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