From 91c9909dc4649812298ca23fc996e756730ed0e2 Mon Sep 17 00:00:00 2001 From: Maurice Date: Sat, 4 Jul 2026 23:27:06 +0200 Subject: [PATCH] feat(plugins): enable the plugin system by default The runtime and the Admin -> Plugins panel are now available out of the box; TREK_PLUGINS_ENABLED becomes an opt-out (set it to false to switch the whole system off). Installed plugins are still registered inactive and have to be activated one by one, so no third-party code runs until an admin turns a specific plugin on. Update the kill-switch default test and the plugin/env-var wiki pages to match. --- server/src/nest/plugins/kill-switch.ts | 17 +++++++++++------ .../tests/unit/plugins/plugins-service.test.ts | 13 ++++++++++++- wiki/Environment-Variables.md | 6 +++--- wiki/Plugins.md | 14 +++++++++----- 4 files changed, 35 insertions(+), 15 deletions(-) diff --git a/server/src/nest/plugins/kill-switch.ts b/server/src/nest/plugins/kill-switch.ts index 995ca255e..0804b8d82 100644 --- a/server/src/nest/plugins/kill-switch.ts +++ b/server/src/nest/plugins/kill-switch.ts @@ -1,10 +1,15 @@ /** - * Plugin-system kill switch (#plugins). Off by default — a brand-new, high-risk - * surface an instance owner must deliberately opt into. Lives in its own module - * (not config.ts) so the many tests that mock config with a partial export set - * don't have to know about it: the plugin runtime reads the env directly here. - * Read at call time so tests and runtime env changes take effect immediately. + * Plugin-system kill switch (#plugins). On by default — the runtime and the + * Admin → Plugins panel are available out of the box, but installed plugins + * still have to be activated one by one, so no third-party code runs until an + * admin turns a specific plugin on. Set TREK_PLUGINS_ENABLED=false to switch the + * whole system off (installed plugins stay on disk, deactivated). Lives in its + * own module (not config.ts) so the many tests that mock config with a partial + * export set don't have to know about it: the plugin runtime reads the env + * directly here. Read at call time so tests and runtime env changes take effect + * immediately. */ export function pluginsEnabled(): boolean { - return (process.env.TREK_PLUGINS_ENABLED || '').trim().toLowerCase() === 'true'; + const v = (process.env.TREK_PLUGINS_ENABLED || '').trim().toLowerCase(); + return !['false', '0', 'off', 'no'].includes(v); } diff --git a/server/tests/unit/plugins/plugins-service.test.ts b/server/tests/unit/plugins/plugins-service.test.ts index 788326df7..a93917c17 100644 --- a/server/tests/unit/plugins/plugins-service.test.ts +++ b/server/tests/unit/plugins/plugins-service.test.ts @@ -43,7 +43,18 @@ describe('PluginsService.list', () => { expect(out.plugins[0]).toMatchObject({ id: 'flight', name: 'Flight', status: 'inactive' }); }); - it('reports disabled when the kill switch is off (default)', () => { + it('reports enabled by default (no kill switch set)', () => { + testDb + .prepare('INSERT INTO plugins (id, name, description, type, status, version) VALUES (?,?,?,?,?,?)') + .run('flight', 'Flight', 'desc', 'widget', 'inactive', '1.0.0'); + + const out = new PluginsService().list(); + expect(out.enabled).toBe(true); + expect(out.plugins).toHaveLength(1); + }); + + it('reports disabled when the kill switch is off (TREK_PLUGINS_ENABLED=false)', () => { + process.env.TREK_PLUGINS_ENABLED = 'false'; const out = new PluginsService().list(); expect(out.enabled).toBe(false); expect(out.plugins).toEqual([]); diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 2c741667f..17c88072b 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -253,11 +253,11 @@ seeded. ## Plugins -The plugin runtime is **off unless you opt in**. It only starts when `TREK_PLUGINS_ENABLED` is exactly `true`; otherwise the Admin → Plugins panel shows a disabled banner and no plugin code runs. See [Plugins](Plugins) for the full system and [Plugin-Permissions](Plugin-Permissions) for the isolation model. +The plugin system is **on by default**. The runtime and the Admin → Plugins panel are available out of the box, but installed plugins still have to be activated one by one — so no third-party code runs until an admin turns a specific plugin on. Set `TREK_PLUGINS_ENABLED=false` to switch the whole system off. See [Plugins](Plugins) for the full system and [Plugin-Permissions](Plugin-Permissions) for the isolation model. | Variable | Description | Default | |-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| -| `TREK_PLUGINS_ENABLED` | Master switch for the plugin runtime. Must be exactly `true` (case-insensitive) to enable. Setting it back to `false` is a kill switch — installed plugins stay on disk but nothing runs. | `false` | +| `TREK_PLUGINS_ENABLED` | Master switch for the plugin system. Enabled unless set to `false` (also accepts `0`, `off`, `no`, case-insensitive). Turning it off is a kill switch — installed plugins stay on disk but nothing runs. | enabled | | `TREK_PLUGINS_DIR` | Directory where installed plugin **code** is stored. Persist it as a volume if you use plugins. | `/plugins` | | `TREK_PLUGINS_DATA_DIR` | Directory for each plugin's own **data** (its private SQLite file). Kept separate from the code tree; persist it as a volume too. | `/plugins-data` | | `TREK_PLUGIN_REGISTRY_URL` | Override the plugin registry index the *Discover* tab browses. Point it at your own fork or mirror of the registry. | `https://raw.githubusercontent.com/mauriceboe/TREK-Plugins/main/dist/index.json` | @@ -265,7 +265,7 @@ The plugin runtime is **off unless you opt in**. It only starts when `TREK_PLUGI | `TREK_PLUGIN_PERMISSIONS` | Set to `off` to opt **out** of the Node.js OS-level permission sandbox for plugin child processes (not recommended). Any other value keeps the sandbox on. | `on` | | `TREK_PLUGIN_ALLOW_PRIVATE_EGRESS`| Set to `on` to let a plugin's declared outbound hosts resolve to private/internal addresses (e.g. a service on your LAN). By default connections to private, loopback, link-local and metadata addresses are refused. | off (private egress blocked) | -All of these are optional — the defaults are safe, and only `TREK_PLUGINS_ENABLED` is needed to turn the system on. +All of these are optional — the defaults are safe. Set `TREK_PLUGINS_ENABLED=false` if you want to switch the plugin system off entirely. --- diff --git a/wiki/Plugins.md b/wiki/Plugins.md index bfbaee106..38c1e89b0 100644 --- a/wiki/Plugins.md +++ b/wiki/Plugins.md @@ -24,17 +24,21 @@ A plugin declares one `type` in its manifest, which decides where it surfaces: ## Enabling plugins -The plugin runtime is **off by default**. To turn it on, set the environment -variable to exactly `true` and restart: +The plugin system is **on by default** — the runtime and the **Admin → Plugins** +tab are available out of the box. Installed plugins still have to be activated +one by one, so nothing third-party runs until you turn a specific plugin on. + +To switch the whole system off, set the environment variable to `false` and +restart: ```yaml environment: - - TREK_PLUGINS_ENABLED=true + - TREK_PLUGINS_ENABLED=false ``` When it's off, the **Admin → Plugins** tab shows a "turned off -(TREK_PLUGINS_ENABLED)" banner and nothing runs. Setting it back to `false` is a -kill switch — installed plugins stay on disk, deactivated and harmless. +(TREK_PLUGINS_ENABLED)" banner and nothing runs. Installed plugins stay on disk, +deactivated and harmless, until you turn the system back on. ## The isolation model — what a plugin can and can't do