k1nq/TREK

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

Files

T

Maurice 6465ea09f1 feat(plugin-sdk): one-command publishing — pack, entry, release

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.

2026-07-04 13:57:45 +02:00

3.2 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.

Publish

The SDK does the fiddly parts (zipping, hashing, sizing, writing the registry entry) so you don't compute anything by hand:

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 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.

3.2 KiB Raw Blame History