mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-19 05:26:47 +00:00
mauriceboe
17f3c86967
Widget plugins can now declare capabilities.widget.slot 'hero' to render as a transparent, click-through overlay sitting on the boarding-pass bar's top edge (migration 157 persists capabilities; manifest validation server+SDK, feed exposes the slot, dashboard mounts hero frames above the pass). Sidebar stays the default slot. Replaces the trip-countdown example with Koffi, the TREK mascot: an animated suitcase with a 14-state behavior engine driven by real trip data — walking, waving, napping, trolley rolls, passport-stamp stickers, a split-flap luggage- tag countdown under 7 days, and sunglasses while the trip runs. Validated by the SDK suite like any author plugin; published as mauriceboe/trek-plugin-koffi in the registry. Migrations 156/157 follow the idempotent ALTER pattern (the reconciliation test re-runs everything from v135, so duplicate-column must stay non-fatal).
trek-plugin-sdk
The SDK for building TREK plugins.
Scaffold a plugin
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
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
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.
Exports
definePlugin(def)+ all the plugin types (PluginContext,PluginRoute,PluginJob,PhotoProvider,CalendarSource).PLUGIN_API_VERSION— embed asapiVersionin your manifest.validateManifest(json)— the same checks the registry CI runs.createMockHost(opts)(fromtrek-plugin-sdk/testing).
CLIs
create-trek-plugin <name> --type …— scaffold.trek-plugin validate [dir]— validate the manifest + README locally (predicts the registry CI result).
MIT.