74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
# Plugin Schema
|
|
|
|
All plugin definitions must be valid JSON files following this schema.
|
|
|
|
## Required Fields
|
|
|
|
| Field | Type | Description | Example |
|
|
|-------|------|-------------|---------|
|
|
| `id` | string | Unique identifier (must match filename) | `"awesome-plugin"` |
|
|
| `name` | string | Display name | `"Awesome Plugin"` |
|
|
| `version` | string | Semantic version | `"1.0.0"` |
|
|
| `description` | string | What the plugin does | `"Does awesome things"` |
|
|
| `author` | string | Gitea username of creator | `"litruv"` |
|
|
| `repository` | string | Git repository URL | `"http://synbox.ruv.wtf:8418/litruv/awesome-plugin.git"` |
|
|
|
|
## Optional Fields
|
|
|
|
| Field | Type | Description | Example |
|
|
|-------|------|-------------|---------|
|
|
| `downloadUrl` | string | Direct download URL | `"http://synbox.ruv.wtf:8418/litruv/awesome-plugin/archive/main.zip"` |
|
|
| `homepage` | string | Plugin homepage or documentation | `"http://synbox.ruv.wtf:8418/litruv/awesome-plugin"` |
|
|
| `tags` | array | Category tags | `["utility", "automation"]` |
|
|
| `addedDate` | string | ISO 8601 date | `"2026-04-17T00:00:00.000Z"` |
|
|
| `dependencies` | object | Required dependencies | `{"lodash": "^4.17.21"}` |
|
|
|
|
## Example
|
|
|
|
```json
|
|
{
|
|
"id": "example-plugin",
|
|
"name": "Example Plugin",
|
|
"version": "1.0.0",
|
|
"description": "An example plugin demonstrating the plugin system capabilities",
|
|
"author": "litruv",
|
|
"repository": "http://synbox.ruv.wtf:8418/litruv/Plugin-Example.git",
|
|
"downloadUrl": "http://synbox.ruv.wtf:8418/litruv/Plugin-Example/archive/main.zip",
|
|
"homepage": "http://synbox.ruv.wtf:8418/litruv/Plugin-Example",
|
|
"tags": ["example", "demo"],
|
|
"addedDate": "2026-04-17T00:00:00.000Z"
|
|
}
|
|
```
|
|
|
|
## Validation Rules
|
|
|
|
1. **Filename Match**: Plugin ID must match the filename (without .json extension)
|
|
- ✅ `awesome-plugin.json` with `"id": "awesome-plugin"`
|
|
- ❌ `awesome-plugin.json` with `"id": "different-name"`
|
|
|
|
2. **Version Format**: Must follow semantic versioning (X.Y.Z)
|
|
- ✅ `"1.0.0"`, `"2.5.3"`, `"0.1.0"`
|
|
- ❌ `"1.0"`, `"v1.0.0"`, `"latest"`
|
|
|
|
3. **Author Matching**: For new plugins, author must match PR creator
|
|
- If PR is by user `litruv`, author field must be `"litruv"`
|
|
|
|
4. **Valid URLs**: Repository, downloadUrl, and homepage must be valid URLs
|
|
- ✅ `"http://example.com/repo.git"`
|
|
- ❌ `"not-a-url"`, `"//example.com"`
|
|
|
|
5. **Tags**: If present, must be an array of strings
|
|
- ✅ `["tag1", "tag2"]`
|
|
- ❌ `"tag1,tag2"`, `{"tag": "value"}`
|
|
|
|
## Submission Process
|
|
|
|
1. Create a JSON file in the `plugins/` directory
|
|
2. Filename must be `{plugin-id}.json`
|
|
3. Ensure all required fields are present
|
|
4. Author field must match your Gitea username
|
|
5. Create a Pull Request
|
|
6. Automated validation will run
|
|
7. If valid, PR auto-merges
|
|
8. If invalid, you'll receive comments explaining what to fix
|