phlix-plugins/plugins.schema.json at master · detain/phlix-plugins · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/detain/phlix-plugins/HEAD/plugins.schema.json",
  "title": "Phlix plugin catalog",
  "description": "Schema for a Phlix plugin catalog document (plugins.json). The catalog is the trust root the Phlix server reads to drive admin plugin installs; each entry pins an exact commit (ref) and the sha256 of the codeload tarball for that commit (artifactSha256) so the server can verify the bytes it downloads before installing.",
  "type": "object",
  "required": ["schemaVersion", "name", "plugins"],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": {
      "description": "Catalog format version. Version 2 introduces the per-entry pin (ref + artifactSha256 + version).",
      "const": 2
    },
    "name": {
      "description": "Human-readable catalog name.",
      "type": "string",
      "minLength": 1
    },
    "description": {
      "description": "Optional long description of the catalog.",
      "type": "string"
    },
    "homepage": {
      "description": "Optional catalog homepage URL.",
      "type": "string",
      "format": "uri"
    },
    "plugins": {
      "description": "The plugins this catalog offers. At least one.",
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/plugin" }
    }
  },
  "$defs": {
    "plugin": {
      "type": "object",
      "required": ["name", "title", "type", "repo", "ref", "artifactSha256", "version"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "description": "Plugin manifest name. MUST match the server's HttpInstaller::guardPluginName() regex byte-for-byte.",
          "type": "string",
          "pattern": "^phlix-plugin-[a-z0-9][a-z0-9-]*$"
        },
        "title": {
          "description": "Display name shown in the admin Plugins UI.",
          "type": "string",
          "minLength": 1
        },
        "type": {
          "description": "Plugin category. Enum so typos fail validation. Values that also exist in the server-side manifest enum (Phlix\\Shared\\Plugin\\ManifestType, mirrored in phlix-shared/schemas/manifest.schema.json) MUST be spelled identically — an entry's type should match the `type` in the plugin's own plugin.json at the pinned ref. NOTE: this enum and the manifest enum are not identical sets today: 'player' and 'integration' are catalog-only, and the manifest enum additionally offers auth-provider, library-type, tuner, transcoder-hook, arr-integration and analytics-sink, which no catalog entry has needed yet. 'ui-theme' was added for theme plugins (a plugin whose entry class implements Phlix\\Theming\\ThemeSourceInterface). The server does NOT dispatch on this field — PluginLoader::enable() registers a theme source off the `instanceof` alone and CatalogEntry carries `type` as a free-form display string — so this value is for validation and for the admin UI's category label, not for capability selection.",
          "type": "string",
          "enum": [
            "metadata-provider",
            "scrobbler",
            "subtitle-provider",
            "notifier",
            "player",
            "integration",
            "ui-theme"
          ]
        },
        "summary": {
          "description": "Optional one-line description.",
          "type": "string"
        },
        "description": {
          "description": "Optional long description.",
          "type": "string"
        },
        "repo": {
          "description": "Human repository URL. For the official catalog this is constrained to github.com under the detain/ org. A forked catalog can relax this pattern.",
          "type": "string",
          "format": "uri",
          "pattern": "^https://github\\.com/detain/phlix-plugin-[a-z0-9][a-z0-9-]*/?$"
        },
        "ref": {
          "description": "The 40-char lowercase commit sha this entry is pinned to (an exact commit in the plugin repo, never a branch or tag). The server downloads /archive/<ref>.tar.gz, not HEAD.",
          "type": "string",
          "pattern": "^[0-9a-f]{40}$"
        },
        "artifactSha256": {
          "description": "Bare 64-hex sha256 of the codeload tarball at the pinned ref (github.com/<owner>/<repo>/archive/<ref>.tar.gz). No 'sha256:' prefix. MUST move in lockstep with ref.",
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "version": {
          "description": "The plugin's semver at the pinned ref (read from its plugin.json).",
          "type": "string",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?$"
        },
        "minServerVersion": {
          "description": "Minimum Phlix server version required to run this plugin (from its plugin.json phlix_min_server_version at the pinned ref). The admin UI shows 'incompatible' before download when the running server is older.",
          "type": "string",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?$"
        },
        "maxServerVersion": {
          "description": "Maximum Phlix server version supported by this plugin (exclusive upper bound). Optional.",
          "type": "string",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?$"
        },
        "verified": {
          "description": "Whether this entry has been reviewed and verified by the catalog maintainer. An un-verified entry (false) is install-blocked by the server in default-deny mode.",
          "type": "boolean"
        },
        "deprecated": {
          "description": "Whether this plugin entry is deprecated. Deprecated entries may still be installable but the server will warn operators.",
          "type": "boolean"
        },
        "yanked": {
          "description": "Whether this plugin version has been yanked (withdrawn). A yanked entry is hidden from the catalog listing but still known to the server for operators who have it installed.",
          "type": "boolean"
        },
        "deprecationMessage": {
          "description": "Human-readable message shown when a deprecated or yanked entry is encountered. Explains why and what to use instead.",
          "type": "string"
        },
        "author": {
          "description": "Optional catalog-declared author/owner.",
          "type": "string"
        },
        "tags": {
          "description": "Optional free-form tags.",
          "type": "array",
          "items": { "type": "string" }
        }
      }
    }
  }
}