Simplified: Use git-based directory with Gitea Actions instead of server

2026-04-17 02:01:51 +10:00
parent bd535138d6
commit 42a1712175
7 changed files with 1194 additions and 143 deletions
--- a/README.md
+++ b/README.md
@@ -1,73 +1,26 @@
 # Plugin Directory

-Automated plugin registry with PR validation and auto-merge capabilities for the Plugin Host system.
+A simple git-based plugin registry for the Plugin Host system.

-## Features
+## 📦 What This Is

- 🤖 **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
+A collection of JSON files that describe available plugins. The Plugin Host fetches these definitions directly from the git repository.

-## Setup
+## 🚀 How It Works

-### 1. Install Dependencies
+1. Plugin authors create a JSON file in `plugins/` directory
+2. Submit via Pull Request
+3. Gitea Actions validate the submission
+4. If valid, maintainer merges the PR
+5. Plugin Host automatically discovers the new plugin

-```bash
-npm install
-```
+## 📝 Submitting a Plugin

-### 2. Configure Environment
+### 1. Fork this repository

-Copy `.env.example` to `.env` and fill in your Gitea details:
+### 2. Create your plugin definition

-```bash
-cp .env.example .env
-```
-
-Edit `.env`:
-```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
-
-```bash
-npm start
-```
-
-For development with auto-reload:
-```bash
-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
+Create `plugins/your-plugin-id.json`:

 ```json
 {
@@ -76,100 +29,93 @@ npm run dev
  "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"
+  "repository": "http://synbox.ruv.wtf:8418/you/your-plugin.git",
+  "downloadUrl": "http://synbox.ruv.wtf:8418/you/your-plugin/archive/main.zip",
+  "homepage": "http://synbox.ruv.wtf:8418/you/your-plugin",
+  "tags": ["category", "keywords"]
 }
 ```

-**Required Fields:**
- `id` - Unique identifier (must match filename without .json)
+**Required fields:**
+- `id` - Must match filename (without .json)
 - `name` - Display name
 - `version` - Semantic version (X.Y.Z)
- `description` - What the plugin does
- `author` - Your Gitea username
+- `description` - Brief description
+- `author` - Your Gitea username (must match PR creator)
 - `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
+### 3. Create Pull Request

-## API Endpoints
+Gitea Actions will automatically validate:
+- ✅ File is in `plugins/` directory
+- ✅ File is valid JSON
+- ✅ All required fields present
+- ✅ ID matches filename
+- ✅ Author matches your username
+- ✅ Version format is valid
+- ✅ URLs are valid

-### List All Plugins
+### 4. Merge

-```bash
-GET /plugins
+If validation passes, maintainer will merge your PR.
+
+## 🗑️ Removing Your Plugin
+
+Only plugin authors can remove their own plugins:
+
+1. Fork this repository
+2. Delete `plugins/your-plugin-id.json`
+3. Create Pull Request
+
+## 🔄 Updating Your Plugin
+
+1. Fork this repository
+2. Edit `plugins/your-plugin-id.json`
+3. Update version number and any other fields
+4. Create Pull Request
+
+## 📋 Plugin Schema
+
+See [SCHEMA.md](SCHEMA.md) for full schema documentation.
+
+## 🔍 Validation Rules
+
+PRs must:
+- Only modify files in `plugins/` directory
+- Only modify `.json` files
+- Have valid JSON
+- Match the plugin schema
+- Have author field matching PR creator
+- Have plugin ID matching filename
+
+## 🏗️ Directory Structure
+
+```
+Plugin-Directory/
+├── plugins/
+│   ├── example-plugin.json
+│   ├── your-plugin.json
+│   └── ...
+├── .gitea/
+│   ├── workflows/
+│   │   └── validate-pr.yml
+│   └── scripts/
+│       └── validate-pr.js
+└── README.md
 ```

-Response:
-```json
-{
-  "plugins": [...],
-  "count": 10
-}
+## 🔗 Plugin Host Integration
+
+The Plugin Host fetches plugin definitions from:
+```
+http://synbox.ruv.wtf:8418/litruv/Plugin-Directory/raw/branch/main/plugins/
 ```

-### Get Specific Plugin
+No server needed - just static JSON files served by Gitea!

-```bash
-GET /plugins/:pluginId
-```
+## 📖 Example Plugins

-### Health Check
-
-```bash
-GET /health
-```
-
-### Webhook Endpoint
-
-```bash
-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
+- [example-plugin.json](plugins/example-plugin.json) - Reference implementation

 ## License