k1nq/TREK

mirror of https://github.com/mauriceboe/TREK.git synced 2026-10-18 21:16:47 +00:00

Files

T

mauriceboe 7318ee0d42 feat(plugins): trek-plugin-sdk package — types, mock host, scaffolder, validator (M6)

The author-facing SDK, a standalone dependency-free package (not wired into the
app workspaces, so it can't affect the app build).

- definePlugin + the full plugin type surface (PluginContext, PluginRoute,
  PluginJob, PhotoProvider, CalendarSource) mirroring what the isolated runtime
  injects; PLUGIN_API_VERSION.
- createMockHost (trek-plugin-sdk/testing): a PluginContext that enforces the
  SAME permission model + membership checks, so authors can unit-test that their
  plugin degrades gracefully — no running TREK needed.
- validateManifest: the exact rules the registry CI runs, so a local pass
  predicts a CI pass.
- CLIs: create-trek-plugin (scaffolds a working plugin + README + starter iframe)
  and trek-plugin validate (manifest + README sanity).

Consolidating the server loader to import this shared validator is a follow-up.

2026-07-03 17:44:55 +02:00

1.8 KiB

Raw Blame History

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 as apiVersion in your manifest.
validateManifest(json) — the same checks the registry CI runs.
createMockHost(opts) (from trek-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.

1.8 KiB Raw Blame History