trek-plugin-sdk

v1.7.0

Published

21 days ago

SDK for building TREK plugins: types, definePlugin, a mock host, manifest validation, and the create-trek-plugin / trek-plugin CLIs.

0High
0Medium
0Low

mauriceboetger

trek plugin sdk

trek-plugin-sdk

The SDK for building TREK plugins.

The path is four commands: create → dev → status → publish. Everything else the CLI can do is a step one of those already does for you.

Scaffold a plugin

npx trek-plugin-sdk                        # no command? a guided menu of everything below
npx trek-plugin-sdk create                 # interactive wizard (id, type, icon, permissions, egress)
npx trek-plugin-sdk create my-plugin --type widget   # or non-interactive
cd my-plugin

The wizard asks for the id, type, icon (validated against lucide), permissions, egress hosts and required addons, and offers to initialize a git repo and install dependencies for you. In a non-interactive shell (CI, pipes) every command stays flag-driven with plain output — no prompts, and machine output (entry JSON, pack --json, PR URLs) stays on stdout.

What you get runs and packs immediately — but it is not publishable yet: the README is a template and there is no screenshot. That is deliberate. Writing those is your job, and status tells you exactly what is left.

Develop with a live reload loop

dev runs your plugin locally — no full TREK needed. It injects a ctx that enforces exactly the permissions your manifest grants (an ungranted call throws PERMISSION_DENIED, so you catch missing grants), backs db:own with a real SQLite file, serves your routes and your page/widget UI, and reloads on save.

npx trek-plugin-sdk dev        # http://localhost:4317 — dashboard, routes, UI

Open /preview to see a page/widget rendered in a real sandboxed frame with a theme/accent/appearance toggle (trek.invoke() is proxied to your routes). Hit a route as an unauthenticated request with ?_anon=1. Drop a dev-fixtures.json (trips, users, config) next to your manifest to feed ctx.trips / ctx.users.

Know where you are

npx trek-plugin-sdk status        # never fails — it's a map, not a gate

status runs every check the TREK-Plugins registry enforces that can be answered without a network — which is nearly all of them — and prints the whole journey as a checklist grouped by stage (Manifest, Code, Docs, Release, Repo): what passes, what does not, and the one command to run next. Run it whenever you are not sure what to do; it deliberately never exits non-zero.

validate is the same checks with an exit code. It is the form for scripts and CI; status is the form for humans. A plugin that passes validate will pass every registry gate that does not require the tag and the release to exist — those four run in preflight, which publish does for you.

Build a native UI (page / widget)

The UI is a sandboxed, opaque-origin iframe that can't load TREK's stylesheet — so the SDK ships it. Put one line in your client/index.html <head>:

<!-- trek:ui -->

dev and pack expand it into the inlined design kit: token-driven styles that follow the host's theme and accent (glass, cards, .trek-btn, .trek-input, .trek-chip, .trek-row, hover), plus a window.trek bridge:

trek.onContext((ctx) => { /* ctx.theme, ctx.tokens, ctx.appearance, ctx.user, ctx.tripId */ })
const data = await trek.invoke('/status')   // calls your own route, host-proxied
trek.notify('success', 'Saved')

Keep UI state for this browser tab

The opaque frame cannot use browser storage directly. The bridge provides host-managed, JSON-only session state instead. It survives an iframe remount and page reload in the same browser tab, but is not durable data. Do not use it to store secrets.

// Default: this user + this plugin + this browser tab.
await trek.session.set('dismissed-onboarding', true)
const dismissed = await trek.session.get('dismissed-onboarding')

// Explicitly partition state by the trip in view (fails without a trip context).
await trek.session.set('filters', ['flight', 'hotel'], { scope: 'trip' })

get() returns undefined for a missing key. set, get, remove, and clear accept { scope: 'plugin' | 'trip' }; plugin is the default. Use your plugin's own logical key (for example reservation:88:expanded) for any finer partitioning. Each plugin or individual trip scope is limited to 32 keys, 64 characters per key, and 1 KiB per JSON value.

The kit applies the theme, mirrors the appearance flags (reduced-motion, no-transparency) and auto-reports your height. It also upgrades any native <select> into a host-styled, keyboard-accessible dropdown that matches TREK — the OS-drawn popup never could. Write a plain <select> and it just works; add data-trek-native to opt a field out. See the Plugin Development wiki for the full component + token reference.

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.

Settings

Declare settings in trek-plugin.json; TREK renders the form, you write no settings UI.

"settings": [
  { "key": "api_url", "label": "API URL", "default": "https://api.example", "required": true },
  { "key": "retries", "label": "Retries", "input_type": "number", "default": 3 },
  { "key": "api_key", "label": "API key", "scope": "user", "secret": true, "required": true },
  { "key": "region", "label": "Region", "input_type": "select",
    "options": [{ "value": "eu", "label": "EU" }, { "value": "us", "label": "US" }], "default": "eu" }
]

| Attribute | Meaning | |---|---| | key | Identifier (^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$). | | scope | instance (default) — set once by the admin, arrives in ctx.config. user — per user, read with await ctx.settings.get(key). | | input_type | text (default), password, number, checkbox, select (with options). | | default | The field's value wherever nobody set one. The form pre-fills it and the runtime resolves it — ctx.config.api_url / ctx.settings.get('region') return it until someone saves something else — so a plugin with sensible defaults works before anyone opens the form. Satisfies required. Not allowed on a secret (the manifest is public); must be a boolean on a checkbox and one of the options when declared. trek-plugin dev seeds its fixtures from these too. | | required | Enforced: the form refuses Save while the field is blank, and the host answers 400 { error: 'Missing required setting "<key>"' } if a save reaches it anyway. A checkbox is exempt (that would be consent, not a setting). A required scope:'user' field also gates whether a notification channel dispatches to that user. | | secret | Encrypted at rest, decrypted only into the server-side ctx.config / ctx.settings, masked to the browser, never sent to the iframe. | | label, placeholder, hint | Form text. | | options | [{ "value", "label" }] for a select (bare strings are accepted and coerced). | | oauth | Descriptive metadata only — for a host-brokered flow see the OAuth broker below. |

Any other attribute is silently dropped at install. trek-plugin validate warns on one (manifest.settings-known-keys) so a typo like "defalt" doesn't quietly do nothing.

Actions

Up to 8 buttons the host renders on a settings form, declared in trek-plugin.json and implemented in definePlugin({ actions: { <key>: async (ctx) => ({ ok, message }) } }):

"actions": [
  { "key": "testConnection", "label": "Test connection", "hint": "Pings the API." },
  { "key": "purgeCache", "label": "Purge cache", "scope": "instance", "danger": true }
]

| Attribute | Meaning | |---|---| | scope | user (default) — renders on the user Settings tab and runs as the clicking user. instance — renders in the admin instance-settings dialog and runs as the clicking admin. The default differs from settings fields on purpose: existing manifests keep their user-tab buttons. A host older than TREK 4.2.0 (which introduced action scope) ignores this field entirely and renders the button on every user's Settings tab, running it as each user — so if you declare scope: "instance", set the manifest's trek range floor to >=4.2.0 or the button will run in the wrong place on an older host. | | danger | Rendered destructive; the host asks for confirmation first. | | hint | Shown beside the button (≤ 200 chars). |

Either way the handler gets the clicking person as acting user: ctx.config is the instance config, ctx.settings.get() returns their own user value, and trip reads are membership-checked against them. Return { ok, message } or throw to report a failed action (the host shows the message, emoji-stripped, ≤ 200 chars). An instance action is disabled in the dialog until the plugin is active — there is no child process to run it. In the mock host, pass declaredActions: ['testConnection', { key: 'purgeCache', scope: 'instance' }] and drive either with drv.action(key).

ctx.config is frozen at activation — the host re-spawns the plugin when the admin saves. ctx.settings.get() is live per call and returns undefined in a userless context (onLoad, jobs, scheduler) — fall back to ctx.config there.

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.

Runtime limits

The host enforces these limits on every ctx call and hook invocation. They are generous for a legitimate plugin and only bite a runaway or abusive one — build against them so dev/mock-host behavior matches production.

| Area | Limit | |---|---| | ctx.ai | 200 calls/day per plugin (UTC midnight rollover); past it throws "daily AI budget exhausted (resets at UTC midnight)" | | ctx.notify | 100 calls/day per plugin (UTC midnight rollover); past it throws "daily notification budget exhausted (resets at UTC midnight)" | | RPC (every ctx.* call) | burst 60, sustained 20/s, 16 in-flight per plugin; a throttled call is refused with HOST_ERROR: rate limit exceeded — slow down ctx.* calls | | ctx.db (your own sqlite) | 256 MB per plugin | | ctx.meta | 64 KB per value, 256 chars per key, 100 keys per (plugin, entity) | | Plugin process | 300 MB RSS ceiling; auto-disabled after 5 crashes in 5 minutes | | Event redelivery buffer | 200 events held per plugin, dropped unreplayed after 15 minutes |

Hook contribution caps (declarative content the host renders — a slow/failing call is skipped, never fatal):

| Hook | Cap | |---|---| | pdfSectionProvider | ≤5 sections per provider | | atlasLayerProvider | ≤3 layers per provider | | mapMarkerProvider | ≤200 markers per provider | | warningProvider | ≤20 warnings per provider, each message ≤300 chars | | placeDetailProvider | ≤12 items per provider | | photoProvider | ≤60 photos per page | | calendarSource | ≤500 events per source per request | | tableContributor | ≤20 columns / ≤10 actions per entity | | tripCardProvider | ≤4 badges per trip, ≤240 total per provider |

OAuth broker

ctx.oauth.getAccessToken() is host-brokered outbound OAuth: the plugin never becomes a direct OAuth client. The host runs the whole flow (authorize → callback → token exchange → refresh) with PKCE and a 10-minute state TTL, and holds the refresh token + client secret — a plugin only ever sees a short-lived access token for the ACTING USER, or null when they haven't connected (or in a userless context).

Provider config is the plugin's admin-owned INSTANCE settings — declare scope:'instance' manifest fields named oauth_authorize_url, oauth_token_url, oauth_scopes (optional), oauth_client_id, oauth_client_secret, and the admin fills them in from Settings → Plugins → Connect. Both endpoint URLs must be https and may not point at loopback, .local/.internal names, or private/metadata addresses — the host refuses to start a flow against them. The host exposes /api/plugin-oauth/:id/status|connect|callback|disconnect to drive the connect UI; plugin code itself only ever calls getAccessToken().

Capture the screenshot

The registry requires a screenshot that resolves to a real image, and the store card shows it. shot boots the dev server, renders your plugin in the same themed frame TREK uses, and writes a 1600×900 docs/screenshot.png:

npm i -D playwright && npx playwright install chromium   # once
npx trek-plugin-sdk shot                                 # --dark for the dark theme

Playwright is deliberately not a dependency of this SDK — it ships a browser, and most authors never need one. An integration plugin has no UI to render, so shot cannot help; screenshot the TREK surface your plugin changes instead.

Publish — one command

Commit and push your plugin to its public GitHub repo, then:

npx trek-plugin-sdk publish --repo you/repo --tag v1.0.0

publish is the whole release, in five steps and in this order:

check — every registry gate that can be checked locally
pack — build plugin.zip
release — git tag, push, and cut the GitHub release with the artifact
preflight — the gates that need the tag and the release to exist
submit — open the PR against the TREK-Plugins registry

Step 1 comes first for a reason: a GitHub release is effectively immutable, because the registry pins its sha256. If a check fails, nothing is packed, tagged, pushed or released — so you can fix it and re-run against the same version. (--no-checks skips step 1; it is an escape hatch for a re-run, never right on a first publish.)

Needs git and an authenticated gh. It prints the PR URL at the end.

Updating a listed plugin: bump version in the manifest, commit, and run publish again with the new tag — it detects the existing entry and prepends the new version, newest-first. Your TREK-Plugins fork is fast-forwarded automatically before the PR branch is cut, so a fork left behind doesn't break the submit (a diverged fork gets a warning and the gh repo sync --force command to fix it).

When a publish fails

A failure after the release is cut (a preflight or PR problem) rolls back exactly what that run created — the GitHub release, the pushed tag, the local tag — so the same tag is free to re-run against once you've fixed the problem. Nothing that existed before the run is ever touched. Pass --keep-release to keep the release instead; the error then prints the manual cleanup commands.

Two related conveniences:

A leftover tag from an earlier failed run (it has no release and doesn't point at HEAD) is recognised as debris and moved to your current commit instead of silently releasing the stale one.
trek-plugin unrelease <vX.Y.Z> --repo you/repo deletes a stranded release + remote tag + local tag in one go. It checks the published registry index first and refuses to touch a version that is actually published — those artifacts are immutable (the registry pins their sha256), so the only way forward there is a new version.

Prefer to drive the steps yourself? They still exist individually — pack, release (pack → GitHub release → entry), preflight, submit (opens the PR), and entry (just prints the JSON).

Signing (recommended — `publish` offers it)

In a terminal, publish asks whether to sign, and creates the key for you if you have none — you don't have to know --sign or keygen exist. Scripts and CI are never prompted: pass --sign.

A signature proves the artifact came from you, not just that its bytes match what the registry saw. Signing is dependency-free Ed25519 over the artifact bytes.

It is a one-way door you may walk through late:

Unsigned throughout is fine — the sha256 pin is the only guarantee, and TREK accepts it.
Unsigned → signed later breaks nobody. Nothing is pinned until a signed version installs, so adding a key at v1.4.0 is a real option, not a lost cause. The registry does require every version signed once your key appears in the entry — your first signed update retro-signs the older versions for you (each pinned artifact is downloaded, verified against its sha256, and signed with the same key).
Signed → unsigned is refused forever, on every instance that already has the plugin. publish refuses that at step 1, before anything is tagged or released.

So back the key up (~/.trek-plugin/signing.key). Losing it means you cannot ship an update to your own plugin without a registry maintainer override.

npx trek-plugin-sdk publish --repo you/repo --tag v1.1.0 --sign   # or just answer the prompt

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.
settingDefaults(manifest, scope) — the defaults of one settings scope, keyed by field: what the host resolves for an unset field, and what dev seeds ctx.config / ctx.settings with. Spread it under your own fixtures when calling createMockHost to mirror the host. SETTING_FIELD_KEYS is the attribute list the host stores.
createMockHost(opts) (from trek-plugin-sdk/testing).
TREK_UI_CSS, TREK_THEME_JS, TREK_UI_MARKER, injectTrekUi(html) — the design kit, for authors who inline it themselves (a bundler, a custom build). Most plugins just use the  marker instead.

Commands

Run any of these with npx trek-plugin-sdk <command> (or the short trek-plugin bin if you install the package). trek-plugin help <command> — or trek-plugin <command> --help — prints a full page for any of them.

The path:

create [name] [--type t] [--template blank|notification-channel] [--interactive] — scaffold a plugin; a wizard if you omit the name.
dev [dir] [--port 4317] — run locally with a real request loop, SQLite db:own, and hot reload.
status [dir] — where am I? what's left? Every offline registry gate as a checklist, plus the next command. Never fails.
publish [dir] --repo o/n --tag vX [--sign [key]] [--no-checks] [--no-preflight] — the lot: check → pack → release → preflight → open the PR. In a terminal it offers to sign (and makes you a key); scripts pass --sign.

Also:

validate [dir] — the gate: the same checks as status, but it exits non-zero.
pack [dir] [--out plugin.zip] [--json] — build the artifact, print sha256 + size. Refuses a plugin that could not load; does not enforce the publish gates, because packing is how you sideload a plugin to try it.
shot [dir] [--port 4317] [--out docs/screenshot.png] [--dark] [--no-serve] — capture docs/screenshot.png. Needs Playwright.
keygen [--key file] — create an Ed25519 signing key.
sign [zip] [--key file] — print a signature + public key for an artifact.
entry --repo o/n --tag vX [--merge f] [--sign [key]] [--out f] — emit the registry entry JSON.
preflight [dir] --repo o/n --tag vX [--entry f] [--all] — the registry checks that need the network: the tag resolves to the pinned commit, the released artifact downloads and hashes, the id is not bound to another owner, and an update does not drop or rotate a published signing key.
submit [dir] --repo o/n --tag vX [--registry o/n] [--draft] — open the registry PR for you.
release [dir] --repo o/n --tag vX [--sign [key]] [--merge f] — pack → GitHub release → entry, without opening the PR.
unrelease <vX.Y.Z> [dir] --repo o/n [--yes] — delete a stranded release + remote tag + local tag. Refuses a version that is published in the registry (immutable); --yes consents when the registry index can't be checked.

Update notice

Both CLIs (trek-plugin and create-trek-plugin) tell you when a newer SDK has been published. This matters more than the usual "you're on an old version" nag: the registry entry format, the manifest rules and the permission catalog all move with the TREK host, so a stale SDK can pack and submit an entry that today's registry CI rejects.

It is powered by update-notifier, the standard for npm CLIs:

At most once every 24 hours, a detached background process asks registry.npmjs.org for this package's latest version and caches the answer under $XDG_CONFIG_HOME/configstore/ (or ~/.config/…).
Your command never waits for it — the notice is printed from that cache, so a fresh install learns about an update on a later run.
The notice goes to stderr, so pack --json and entry keep piping clean JSON.

The request is an unauthenticated GET for a public package — the same one npm install makes (npm's servers see your IP, as for any download). TREK has no telemetry, and this isn't any. To turn it off:

export NO_UPDATE_NOTIFIER=1

It is already silent in CI (any CI env var), under NODE_ENV=test, and whenever stdout isn't a terminal (i.e. when piped or redirected).

The SDK tooling in this repo is MIT. Your plugin is your own code under your own license.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

trek-plugin-sdk

Scaffold a plugin

Develop with a live reload loop

Know where you are

Build a native UI (page / widget)

Keep UI state for this browser tab

Write a plugin

Settings

Actions

Test without a running TREK

Runtime limits

OAuth broker

Capture the screenshot

Publish — one command

When a publish fails

Signing (recommended — publish offers it)

Exports

Commands

Update notice

Signing (recommended — `publish` offers it)