k1nq/TREK

mirror of https://github.com/mauriceboe/TREK.git synced 2026-10-19 13:36:48 +00:00

Files

T

mauriceboe 660e4b9dfc docs(plugins): plugin wiki + reference plugin (M7)

- Wiki pages (sync to the GitHub wiki on push to main): Plugins overview + trust
  model, Plugin Development (SDK, definePlugin, ctx, routes/jobs, the client
  bridge, testing with the mock host), Plugin Permissions reference, and
  Publishing (registry PR + CI gates + provenance). Linked from the sidebar.
- Reference plugin plugin-sdk/examples/trip-countdown: a complete, minimal-
  permission widget (reads trip data through ctx, renders in the sandboxed
  iframe via the bridge, filled-in README). Validated in the SDK test suite so it
  passes the exact gate authors face.

2026-07-04 19:11:23 +02:00

3.0 KiB

Raw Blame History

Publishing a Plugin

Plugins are distributed from a static registry — the TREK-Plugins GitHub repo. There is no upload server and no account: you host your plugin in your own GitHub repo and list it with a pull request.

1. Host your plugin

Put your plugin in a public GitHub repo (convention: trek-plugin-<id>). It must contain a trek-plugin.json at the root, a built server/index.js, a filled-in README.md, and (page/widget) a built client/.

2. Tag a release

Tag vX.Y.Z where X.Y.Z equals version in your manifest. Either attach a plugin.zip release asset, or rely on the GitHub source archive at that commit.

3. Validate locally

npx trek-plugin validate .

This runs the exact checks the registry CI runs — a local pass predicts a CI pass.

4. Open a PR against the registry

Add one file, registry/plugins/<id>.json:

{
  "id": "flight-tracker",
  "name": "Flight Tracker",
  "author": "Your Name",
  "description": "Live flight status widget.",
  "repo": "you/trek-plugin-flight-tracker",
  "type": "widget",
  "versions": [{
    "version": "1.0.0",
    "gitTag": "v1.0.0",
    "commitSha": "<40-hex commit the tag points at>",
    "downloadUrl": "https://github.com/you/trek-plugin-flight-tracker/releases/download/v1.0.0/plugin.zip",
    "sha256": "<sha256 of that artifact>",
    "minTrekVersion": "3.2.0",
    "apiVersion": 1,
    "nativeModules": false
  }]
}

CI validates the entry and the artifact, and the maintainer reviews the source at the pinned commit before merging.

What CI enforces

Entry: valid schema · id matches the filename and is a valid slug · reserved namespaces (trek-, official-) blocked · your id is bound to your GitHub owner on first registration (nobody can repoint it later) · homoglyph check · the release tag exists and points at the pinned commit · manifest parity · the artifact's SHA-256 matches the pin · no native binaries · egress[] present when http:outbound is declared.

README: must exist, have the required sections (What it does / Screenshots / Permissions / Setup), contain at least one screenshot that actually resolves, have real content (not the unfilled template), and explain every declared permission.

Provenance & integrity

commitSha pins the exact source the maintainer reviewed (git tags are movable).
sha256 pins the exact artifact bytes TREK will run (release assets are mutable).

TREK verifies the downloaded bytes against sha256 and refuses to install on a mismatch. A reviewedAt date on your entry means a maintainer looked at that exact commit — it is not an ongoing guarantee.

Updating

Add a new version entry (new version/gitTag/commitSha/sha256) to your plugin file and PR it. Instances see the update on their next registry poll; updating is always an explicit admin action, and if a new version requests more permissions the admin must re-approve.

3.0 KiB Raw Blame History