mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-19 21:46:49 +00:00
Maurice
c3c70bcf9d
Publishing a plugin meant hand-building the zip, running shasum + stat, resolving the tag's commit, and hand-writing the whole registry entry. The SDK does all of it now: - `trek-plugin pack` builds plugin.zip in the exact layout the installer reads (own tiny zip writer, so the SDK stays dependency-free and the format can't drift from the reader), enforces the same native-binary and size rules, and prints the sha256 + size. docs/ is left out — the store fetches the screenshot from the repo, so it doesn't belong in the install artifact (Koffi's went from 943 KB to 15 KB). - `trek-plugin entry` emits the ready-to-PR registry entry from the manifest + the packed zip + the git tag: commitSha (deref'd), downloadUrl, sha256, size, and minTrekVersion derived from the manifest's trek range. `--merge` prepends a new version onto an existing entry for updates. - `trek-plugin release` chains pack → gh release → entry. Also: the scaffold now points the README at docs/screenshot.png (the path the store actually fetches, was screenshot-1.png) with a size hint, and stops hard-coding an MIT license — a plugin is the author's own code under their own license. Round-tripped against the real server extractor; 18 tests.
86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# trek-plugin-sdk
|
|
|
|
The SDK for building [TREK](https://github.com/mauriceboe/TREK) plugins.
|
|
|
|
## Scaffold a plugin
|
|
|
|
```bash
|
|
npx create-trek-plugin my-plugin --type integration|page|widget
|
|
cd my-plugin
|
|
# build server/index.js, fill in the README
|
|
npx trek-plugin validate .
|
|
```
|
|
|
|
## Write a plugin
|
|
|
|
```js
|
|
const { definePlugin } = require('trek-plugin-sdk')
|
|
|
|
module.exports = definePlugin({
|
|
async onLoad(ctx) {
|
|
await ctx.db.migrate('001', 'CREATE TABLE cache (k TEXT PRIMARY KEY, v TEXT)')
|
|
},
|
|
routes: [
|
|
{ method: 'GET', path: '/status', auth: true, async handler(req, ctx) {
|
|
return { status: 200, headers: { 'content-type': 'application/json' }, body: '{"ok":true}' }
|
|
}},
|
|
],
|
|
})
|
|
```
|
|
|
|
Your plugin runs in an **isolated child process**. `ctx` is the only way to reach
|
|
TREK, and it grants exactly the permissions your `trek-plugin.json` declares — an
|
|
ungranted call throws `PERMISSION_DENIED`.
|
|
|
|
## Test without a running TREK
|
|
|
|
```js
|
|
import { createMockHost } from 'trek-plugin-sdk/testing'
|
|
|
|
const { ctx, broadcasts } = createMockHost({
|
|
grants: ['db:read:trips', 'ws:broadcast:trip'],
|
|
trips: { 1: { members: [42], data: { id: 1, name: 'Japan' } } },
|
|
})
|
|
// the mock enforces the SAME permission model, so you can prove your plugin
|
|
// degrades gracefully when a permission is missing.
|
|
```
|
|
|
|
## Publish
|
|
|
|
The SDK does the fiddly parts (zipping, hashing, sizing, writing the registry
|
|
entry) so you don't compute anything by hand:
|
|
|
|
```bash
|
|
npx trek-plugin validate # manifest + layout OK?
|
|
npx trek-plugin pack # -> plugin.zip, prints sha256 + size
|
|
gh release create v1.0.0 plugin.zip # attach the artifact to your tag
|
|
npx trek-plugin entry --repo you/repo --tag v1.0.0
|
|
# -> the ready-to-PR registry entry JSON
|
|
```
|
|
|
|
Or in one step: `npx trek-plugin release --repo you/repo --tag v1.0.0` packs,
|
|
creates the GitHub release, and prints the entry. Then paste the entry into a PR
|
|
against [TREK-Plugins](https://github.com/mauriceboe/TREK-Plugins) as
|
|
`registry/plugins/<id>.json`.
|
|
|
|
**Updating** an already-listed plugin: bump `version`, tag, and pass
|
|
`--merge registry/plugins/<id>.json` to `entry` — it prepends the new version,
|
|
keeping the array newest-first.
|
|
|
|
## Exports
|
|
|
|
- `definePlugin(def)` + all the plugin types (`PluginContext`, `PluginRoute`, `PluginJob`, `PhotoProvider`, `CalendarSource`).
|
|
- `PLUGIN_API_VERSION` — embed as `apiVersion` in your manifest.
|
|
- `validateManifest(json)` — the manifest rules the server loader uses.
|
|
- `createMockHost(opts)` (from `trek-plugin-sdk/testing`).
|
|
|
|
## CLIs
|
|
|
|
- `create-trek-plugin <name> --type …` — scaffold a working plugin.
|
|
- `trek-plugin validate [dir]` — check the manifest + layout locally (the manifest rules the registry CI also runs; CI additionally verifies the release, artifact hash and README over the network).
|
|
- `trek-plugin pack [dir] [--out plugin.zip] [--json]` — build the artifact, print `sha256` + `size`.
|
|
- `trek-plugin entry --repo o/n --tag vX [--zip z] [--merge entry.json] [--out f]` — emit the registry entry.
|
|
- `trek-plugin release [dir] --repo o/n --tag vX` — pack → GitHub release → entry, in one go.
|
|
|
|
The SDK tooling in this repo is MIT. Your plugin is your own code under your own license.
|