# 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

```bash
npm install
```

### 2. Configure Environment

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

```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

```json
{
  "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

```bash
GET /plugins
```

Response:
```json
{
  "plugins": [...],
  "count": 10
}
```

### Get Specific Plugin

```bash
GET /plugins/:pluginId
```

### 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

## License

MIT